docs: clean up product documentation (#90)

* docs: clean up product documentation

* docs: clarify Gallery entry point

* docs: remove unnecessary changeset

Author: icecreamx10

README.md

@@ -1,6 +1,8 @@
 # Lynxtron Showcases
 
-A monorepo of Lynxtron showcase apps. **Lynxtron GO** is a playground app (like Electron Fiddle) that can fetch, edit, build, and run any showcase in this repository.
+A monorepo of Lynxtron showcase apps. **Lynxtron Go** is a project editor and
+showcase runner that can fetch, edit, build, and run any showcase in this
+repository.
 
 ## Repository Structure
 
@@ -11,7 +13,7 @@ lynxtron-show-cases/
     cli/            @lynxtron-examples/cli     — CLI for fetching, building, running showcases
   showcases/
     counter/        minimal counter example (full Lynxtron app)
-  lynxtron-go/      Lynxtron GO playground app (IDE shell)
+  lynxtron-go/      Lynxtron Go project editor and showcase runner
   scripts/
     preview.sh          one-command preview flow
     local-registry.sh   local npm registry for testing
@@ -26,11 +28,11 @@ lynxtron-show-cases/
 
 ## Install Notes
 
-The repo pins runtime and toolchain expectations in root `package.json`:
+The repo pins runtime and toolchain expectations in root configuration:
 
-- `engines.node` requires Node.js `>=22`
-- `packageManager` is `pnpm@10.15.1`
-- `pnpm.onlyBuiltDependencies` allows `@lynx-js/lynxtron` and `@lynx-js/lynxtron-builder` to run their install scripts
+- root `package.json` requires Node.js `>=22` and pins `pnpm@10.15.1`;
+- `pnpm-workspace.yaml` allows the Lynxtron runtime, builder, and required
+  native dependencies to run their install scripts.
 
 After `pnpm install`, check whether pnpm skipped any build scripts:
 
@@ -64,7 +66,7 @@ pnpm test
 
 ## Preview Mode (Development)
 
-One command to pack all showcases, start a local npm registry, build Lynxtron GO in preview mode, and launch:
+One command to pack all showcases, start a local npm registry, build Lynxtron Go in preview mode, and launch:
 
 ```bash
 pnpm preview
@@ -73,10 +75,11 @@ pnpm preview
 This will:
 1. Build each showcase and pack its source plus verified `dist_precompiled/` artifact
 2. Start a local Verdaccio registry and publish `@lynxtron-examples/*` packages
-3. Build Lynxtron GO with `LYNXTRON_PREVIEW=1` (bakes `file://` tarball URLs)
-4. Launch Lynxtron GO desktop app
+3. Build Lynxtron Go with `LYNXTRON_PREVIEW=1` (bakes `file://` tarball URLs)
+4. Launch Lynxtron Go desktop app
 
-In the app: **Cmd+P → type `>` → "Open Showcase"** to see the showcase list.
+In the app, open the Gallery from the folder button in the command bar. The
+command palette also exposes showcase commands through **Cmd+P → `>`**.
 
 ```bash
 # Build only (don't launch)
@@ -115,7 +118,7 @@ lynxtron-examples run counter
 lynxtron-examples list
 ```
 
-## Lynxtron GO Commands
+## Lynxtron Go Commands
 
 Open the command palette with **Cmd+P → type `>`**:
 
@@ -148,8 +151,9 @@ test and release a showcase.
 
 Key design decisions:
 - **Full Lynxtron apps**: Each showcase includes host process + Lynx UI, runs as independent desktop window
-- **Thin Launcher**: CLI handles all logic; Lynxtron GO is a UI shell
+- **Host-owned execution**: preload services and the CLI install, verify, build,
+  cache, and launch projects outside the Lynx renderer
 - **Baked-in registry**: Showcase list injected at build time; preview uses `file://` tarballs, release uses GitHub URLs
 - **Unified URL model**: Zero code difference between preview and production
 - **Shared toolchain**: Core Lynx SDK and build tools managed at workspace level
-- **NDJSON protocol**: CLI communicates with Lynxtron GO via newline-delimited JSON on stdout
+- **NDJSON protocol**: CLI communicates with Lynxtron Go via newline-delimited JSON on stdout

docs/showcase-development.md

@@ -31,7 +31,9 @@ This repo relies on root-level pnpm settings to keep Lynxtron binaries installab
 
 - `engines.node` requires Node.js `>=22`
 - `packageManager` is pinned to `pnpm@10.15.1`
-- `pnpm.onlyBuiltDependencies` allows `@lynx-js/lynxtron` and `@lynx-js/lynxtron-builder` to run install scripts
+- `pnpm-workspace.yaml` allows `@lynx-js/lynxtron`,
+  `@lynx-js/lynxtron-builder`, and required native dependencies to run install
+  scripts
 
 After `pnpm install`, verify that no required build scripts were skipped:
 
@@ -93,7 +95,7 @@ mkdir -p showcases/my-app/src/main/desktop
 ```
 
 **Fields:**
-- `showcase.description` — shown in Lynxtron GO's showcase list
+- `showcase.description` — shown in Lynxtron Go's showcase list
 - `showcase.tags` — used for filtering (`beginner`, `advanced`, `animation`, etc.)
 - `showcase.minToolchainVersion` — minimum `@lynxtron-examples/*` version required
 - `showcase.distribution` — omit for a GitHub Release asset; use `"builtin"`
@@ -172,7 +174,7 @@ app.whenReady().then(() => {
 
 Each showcase slice must ship with its own self-contained `tsconfig.json`.
 
-Do not use `extends` that points outside the showcase package, for example `../../../tsconfig.app.json`. Lynxtron GO unpacks showcases into standalone workspaces under `~/.lynxtron-go/showcases/<name>`, so package-external `extends` paths will break diagnostics there even if they work inside this monorepo.
+Do not use `extends` that points outside the showcase package, for example `../../../tsconfig.app.json`. Lynxtron Go unpacks showcases into standalone workspaces under `~/.lynxtron-go/showcases/<name>`, so package-external `extends` paths will break diagnostics there even if they work inside this monorepo.
 
 `src/app/tsconfig.json`:
 
@@ -469,7 +471,7 @@ To test the dist distribution flow locally, use the local registry script.
 This validates the same product promise that preview is meant to protect:
 
 - showcases are packed with verified `dist_precompiled/` artifacts
-- Lynxtron GO can consume them
+- Lynxtron Go can consume them
 - the user does not need to manually rebuild showcase source code just to preview them
 
 Use the local registry script for that flow:
@@ -524,9 +526,9 @@ Merging that PR triggers publishing:
 - **npm** — the public `@lynxtron-examples/*` packages are published to the npm
   registry via `changeset publish` using npm **OIDC trusted publishing** (no
   long-lived `NPM_TOKEN`). `@lynxtron-examples/cli` is `private: true` — it is
-  bundled inside Lynxtron GO at build time and is not published to npm.
+  bundled inside Lynxtron Go at build time and is not published to npm.
 - **GitHub Release** — a `lynxtron-go-v<version>` release is created with:
-  - Lynxtron GO installers: `*.dmg` (macOS) and `*-Setup.exe` (Windows), built via
+  - Lynxtron Go installers: `*.dmg` (macOS) and `*-Setup.exe` (Windows), built via
     `lynxtron-builder`.
   - Every publishable showcase (a package with `showcase` metadata) packed as a
     `.tgz` containing source, `.lynxtron-release.json`, and `dist_precompiled/`.
@@ -545,7 +547,7 @@ to have an OIDC trusted publisher configured, pointing at this repository's
 # Pack every publishable showcase into dist/showcase-artifacts/*.tgz
 node scripts/pack-showcases.mjs
 
-# Build the Lynxtron GO installer for the current platform
+# Build the Lynxtron Go installer for the current platform
 pnpm --dir lynxtron-go run pack        # macOS dmg
 pnpm --dir lynxtron-go run pack:win    # Windows nsis
 ```
@@ -567,7 +569,7 @@ Core Lynx dependencies (`@lynx-js/*`) and build tools (`@lynxtron-examples/confi
 ## Showcase Metadata
 
 The `showcase` field in `package.json` is used for:
-- **Lynxtron GO UI** — name, description, tags shown in the showcase list
+- **Lynxtron Go UI** — name, description, tags shown in the showcase list
 - **Registry generation** — `pnpm run generate-registry` reads this field to produce `showcase-registry.json`
 - **Compatibility checks** — `minToolchainVersion` is compared against the user's workspace
 

lynxtron-go/README.md

@@ -1,6 +1,7 @@
 # Lynxtron Go
 
-A code editor built on Lynxtron (Lynx + Node.js), using Scintilla as the native editor engine.
+A desktop project editor and showcase runner built on Lynxtron (Lynx + Node.js),
+using Scintilla as the native editor engine.
 
 ## Tech Stack
 
@@ -10,94 +11,78 @@ A code editor built on Lynxtron (Lynx + Node.js), using Scintilla as the native
 - **Build**: Rspack + RSpeedy (frontend), CMake (native extension)
 - **Language**: TypeScript (UI/main), C++/Objective-C (native)
 
-## Implemented Features
-
-| Feature | Status |
-|---------|--------|
-| Scintilla native editor | ✅ |
-| Open folder (sidebar + ⌘⇧O) | ✅ |
-| Persistent workspace (auto-restore last folder) | ✅ |
-| File tree with expand/collapse | ✅ |
-| File icons by extension | ✅ |
-| Multi-tab editing | ✅ |
-| File open / switch / close | ✅ |
-| Save file (⌘S) | ✅ |
-| Syntax highlighting via Prism.js (TS/TSX/JS/JSX/CSS/SCSS/Less/JSON/Python/C++) | ✅ |
-| Real-time syntax highlighting while typing (SCN_MODIFIED + 50ms debounce) | ✅ |
-| Extension Host process (TypeScript + CSS/SCSS/Less language services) | ✅ |
-| Language services: TS/JS/JSX/TSX diagnostics via TypeScript Compiler API | ✅ |
-| Language services: CSS/SCSS/Less diagnostics via vscode-css-languageservice | ✅ (⚠️ ICU issue) |
-| Diagnostic squiggle indicators (error/warning/info) via Scintilla Indicator API | 🔧 (implemented, E2E pending) |
-| App menu (File / Edit / View) | ✅ |
-| Quick file picker (⌘P) | ✅ (under test) |
-| Status bar (language, save state) | ✅ |
-| Window screenshot API (includes native NSView) | ✅ |
+## Highlights
+
+- Create, edit, save, build, and run complete Lynxtron projects.
+- Browse the baked-in showcase Gallery and open editable project sources.
+- Edit multiple files in native Scintilla panes with a collapsible project tree.
+- Use a folder-oriented workspace IDE with tabs, search, terminal, output, and
+  problems panels.
+- Get real-time syntax styling plus TypeScript/JavaScript and CSS-family
+  diagnostics from the Extension Host.
+- Import and publish complete projects through GitHub Gists.
+- Choose Lynxtron runtimes, configure launch flags, and inspect process output.
+- Build macOS and Windows installers with bundled runtime and starter assets.
 
 ## Prerequisites
 
 - NodeJS >= 22
-- [LynxDevTool](https://github.com/lynx-family/lynx-devtool/releases/) >= 0.1.1
 - pnpm 10.x
 
+[LynxDevTool](https://github.com/lynx-family/lynx-devtool/releases/) is optional
+and only required for runtime inspection and debugging.
+
 ## Usage Guide
 
+Run commands from the monorepo root.
+
 ### Install Dependencies
 
-```bash
+```sh
 pnpm install
 ```
 
 If pnpm reports ignored build scripts for `@lynx-js/lynxtron` or `@lynx-js/lynxtron-builder`, run `pnpm approve-builds` and allow both packages before launching the app.
 
 ### Development
 
-- **Desktop (Lynxtron)**
-  ```bash
-  npm run dev
-  ```
+```sh
+# Start the renderer and desktop host watchers
+pnpm --dir lynxtron-go dev
+
+# Launch the already-built desktop host with the inspector enabled
+pnpm --dir lynxtron-go run run-dev
+```
 
 ### Build & Start
 
-- **Build for Production**
-  ```bash
-  npm run build
-  ```
+```sh
+# Build all Lynxtron Go assets
+pnpm --dir lynxtron-go build
 
-- **Start Desktop**
-  ```bash
-  npm start
-  ```
+# Build and launch the desktop app
+pnpm --dir lynxtron-go start
 
-- **Start Web**
-  ```bash
-  npm run start:web
-  ```
+# Validate without launching
+pnpm --dir lynxtron-go run typecheck
+pnpm --dir lynxtron-go test
+```
 
 ### Application Packaging
 
-- **Package for macOS (x64)**
-  ```bash
-  npm run pack:mac:x64
-  ```
-
-- **Package for macOS (arm64)**
-  ```bash
-  npm run pack:mac:arm64
-  ```
+```sh
+# Package for the current macOS architecture
+pnpm --dir lynxtron-go pack
 
-- **Package for macOS (Universal)**
-  ```bash
-  npm run pack:mac:universal
-  ```
-
-- **Package for Windows (ia32)**
-  ```bash
-  npm run pack:win
-  ```
+# Package the Windows x64 installer
+pnpm --dir lynxtron-go run pack:win
+```
 
 ## Debugging
 
-For detailed debugging strategies, including how to debug the Renderer, Main Process, and Native Modules, please refer to [Debug Strategy](docs/DEBUG_STRATEGY.md).
+Use `pnpm --dir lynxtron-go run debug:detached` for a detached native-debug
+session. See the [documentation index](docs/README.md) for current architecture
+and archived design documents.
 
 ## AI Assistant Integration (MCP)