chore(cli): docs of plan

Author: LemonNekoGH

AGENTS.md

@@ -13,11 +13,12 @@ The current milestone is limited to:
 4. add desktop Godot CEF compatibility, starting with macOS
 5. stabilize the Kirie plugin shape before adding larger tooling layers
 
-Do not introduce extra packages, adapters, or CLI workflows unless they are
-required to make the current IPC milestone work. The existing `@gd-kirie/ipc`
-package is a thin browser-side transport wrapper; do not expand it into an
-application event or invocation layer unless the user explicitly asks for that
-higher-level work.
+Do not introduce extra packages, adapters, or broad CLI workflows unless they
+are required to make the current IPC milestone work. The existing
+`@gd-kirie/ipc` package is a thin browser-side transport wrapper; do not expand
+it into an application event or invocation layer unless the user explicitly asks
+for that higher-level work. The planned Kirie CLI v1 exception is limited to
+`kirie dev` for desktop development through Vite and Godot.
 
 The mobile IPC v1 experiment keeps Kirie core byte-oriented and CBOR-based with
 text, binary, and data lanes. JSON belongs to callers or adapters, not to Kirie
@@ -43,9 +44,9 @@ reason to expose the full Godot CEF browser API through Kirie.
 - `packages/GdKirie.EventaAdapter`
   .NET 10 Eventa adapter over Kirie text IPC
 - `examples/basic-ipc`
-  the first runnable manual integration target
+  beginner-friendly demo project for the raw IPC flow
 - `examples/eventa-csharp`
-  manual Godot C# Eventa adapter smoke example
+  beginner-friendly demo project for Godot C# Eventa adapter usage
 - `tests/integration`
   exported-app platform bridge regression target
 - `scripts/build.ts`
@@ -111,18 +112,54 @@ label them as anecdotal when they influence a decision.
   scene, under a Godot `Window`, or in another scene structure.
 - Keep window organization, named routing, cross-view forwarding, and prefab
   window helpers above Kirie core until the user explicitly asks for that
-  higher-level work.
+  higher-level work. BrowserWindow remains a dream-level API and should not be
+  implemented in GDScript; future high-level window APIs should target C# and
+  TypeScript packages.
 - Keep the Godot-facing wrapper thin; prefer forwarding to the platform
   singleton over reimplementing platform lifecycle logic in GDScript.
 - Keep `KirieClient` as a thin C# wrapper over the same platform singleton.
   Expose Kirie signals as C# events, and keep internal Godot `Callable` usage as
   bridge plumbing rather than public API.
-- Kirie supports packaged web content sourced from project resources through
-  `res://web` loading on the current native paths. Runtime-mounted Godot packs
-  remain out of scope for that loading path.
+- Kirie supports packaged web content sourced from project resources. The
+  planned Kirie app layout standardizes production web content at
+  `res://src-web/dist/index.html`. When that migration is implemented, drop the
+  previous `res://web` behavior instead of preserving a compatibility layer.
+  Runtime-mounted Godot packs remain out of scope for that loading path.
 - If an API is needed by both GDScript and C#, keep the behavior aligned and
   keep C# as a thin wrapper.
 
+## Planned Kirie CLI Direction
+
+The planned Kirie app layout is:
+
+- `kirie.config.ts`
+- `package.json`
+- `project.godot`
+- `src-godot/`
+- `src-web/`
+- `addons/kirie/`
+- optional `addons/godot_cef/`
+
+Kirie CLI v1 should only implement `kirie dev` for desktop Godot development.
+It should be installed through npm, call Vite's JavaScript API directly, let
+Vite resolve port conflicts, launch Godot as a child process, and inject
+`KIRIE_DEV=1` and `KIRIE_WEB_URL=<resolved Vite URL>`.
+
+Keep `kirie create`, `kirie build`, `kirie export`, addon installation, Godot
+CEF installation, export preset management, and mobile dev targets outside the
+CLI v1 scope. These may be implemented later when explicitly planned. Future
+mobile dev targets should use a unified platform and device selector such as
+`kirie dev ios --device <selector>` or
+`kirie dev android --device <selector>`; do not expose simulator and real device
+as separate user-facing target names.
+
+Kirie enforces Vite for user web source. Advanced Vite options belong in
+`kirie.config.ts` under `web.vite`, but Kirie owns `root`, `base`,
+`server.host`, `server.port`, `server.open`, and `build.outDir`.
+
+Kirie user projects should not contain Capacitor-style `ios/` or `android/`
+native project directories. Native features belong in Godot plugins.
+
 ## Android Packaging Direction
 
 The repository is allowed to evolve internally, but the intended external shape
@@ -291,7 +328,7 @@ configured yet.
 
 ### Validation
 
-- Use `examples/basic-ipc` for manual smoke validation and `tests/integration`
+- Use `examples/basic-ipc` for manual demo validation and `tests/integration`
   for exported-app platform bridge regressions.
 - Run the relevant lint target through mise after changing a covered language:
   - GDScript: `mise run lint:gdscript`
@@ -314,7 +351,7 @@ configured yet.
 - After changing iOS native code under `packages/kirie/native/ios`, always run
   `mise run build:ios-xcframework` before device testing.
 - When changing the IPC shape, make sure at least one real request/response
-  exchange remains manually smoke-tested through `examples/basic-ipc` or covered
+  exchange remains manually exercised through `examples/basic-ipc` or covered
   by integration tests once those tests are migrated to the lane API.
 - When changing `KirieClient`, compile it against the Godot .NET SDK. A platform
   integration smoke test for its C# event API is still pending.
@@ -360,20 +397,21 @@ configured yet.
 - Be explicit about readiness and lifecycle transitions before sending bridge
   messages.
 
-## Planned But Not Yet Configured
+## Configured And Pending Coverage
 
-The following directions are intentional, but they are not fully set up in the
-repository yet. Agents should treat them as targets, not as already-enforced
-infrastructure.
+The following directions are intentional, but some are only partially covered.
+Agents should distinguish already-enforced infrastructure from remaining
+coverage gaps.
 
 - GitHub Actions are configured for lint, Android platform integration, iOS
   platform integration, npm package publishing, and addon release packaging.
   Broader release matrix coverage beyond the current addon zip is still not
   configured.
 - Automated platform integration coverage for the C# `KirieClient` wrapper does
   not exist yet.
-- Desktop Godot CEF integration coverage runs through `tests/integration`.
-  Desktop CI and macOS export coverage are not configured yet.
+- Desktop Godot CEF integration coverage runs through `tests/integration`, with
+  desktop CI configured for macOS, Windows, and Linux. macOS export coverage is
+  still not configured yet.
 - Browser-side Eventa adapter support exists in `@gd-kirie/ipc-eventa`.
 - `GdKirie.EventaAdapter` is a .NET 10-only package. It supports Eventa events
   and unary RPC over Kirie text IPC, keeps Eventa source out of `addons/kirie`,

README.md

@@ -55,8 +55,8 @@ example, and regression-test areas:
 - `packages/ipc`: a thin browser-side transport wrapper for Kirie WebView pages
 - `packages/ipc-eventa`: browser-side Eventa adapter over Kirie text IPC
 - `packages/GdKirie.EventaAdapter`: .NET 10 Eventa adapter over Kirie text IPC
-- `examples/basic-ipc`: the first runnable manual integration example
-- `examples/eventa-csharp`: manual Godot C# Eventa adapter smoke example
+- `examples/basic-ipc`: beginner-friendly demo project for the raw IPC flow
+- `examples/eventa-csharp`: beginner-friendly demo project for Godot C# Eventa adapter usage
 - `tests/integration`: exported-app platform integration tests
 - `scripts/build.ts`: mise task entrypoint re-exports
 - `scripts/build-kirie.ts`: Kirie addon artifact and packaging tasks

docs/architecture.md

@@ -12,10 +12,10 @@ We are standardizing only the minimum plugin shape needed to support:
 - packaged `res://` web resource loading for exported apps
 - a repo-level platform integration test project
 
-Anything beyond that, such as CLI tooling or broad application frameworks, is
-deferred until the IPC model is proven. The current `@gd-kirie/ipc` package is
-intentionally only a browser-side transport wrapper on top of the raw native
-bridge. Eventa adapters live above Kirie and use that low-level text transport.
+Anything beyond that, such as broad application frameworks, is deferred until
+the IPC model is proven. The current `@gd-kirie/ipc` package is intentionally
+only a browser-side transport wrapper on top of the raw native bridge. Eventa
+adapters live above Kirie and use that low-level text transport.
 
 The mobile IPC experiment keeps Kirie core byte-oriented and CBOR-based while
 preserving separate text, binary, and data lanes. Higher-level protocols,
@@ -76,6 +76,9 @@ scene structure that fits their project.
 Kirie core should not own window organization. Optional higher-level helpers may
 later provide prefab window, panel, workspace, cross-view forwarding, or routing
 APIs, but those helpers must live above the low-level WebView and IPC surface.
+Do not add Electron-like BrowserWindow APIs to GDScript; future high-level
+window APIs should live in C# and TypeScript packages, with GDScript remaining
+the low-level plugin substrate.
 
 The public Godot API should primarily let users address WebViews through node
 references:
@@ -88,8 +91,10 @@ references:
 Native implementations may keep internal handles or IDs to manage platform instances.
 Android and iOS use private view IDs only to route callbacks back to the owning `KirieNode`; public routing names, browser-driven cross-view forwarding, and window helper APIs are deferred higher-level concerns.
 
-Kirie supports loading packaged offline web content from Godot project resources
-through the `res://web` path described below.
+Kirie supports loading packaged offline web content from Godot project
+resources. The current native resolvers can serve packaged `res://` paths. The
+planned Kirie CLI app layout standardizes production web content at
+`res://src-web/dist/index.html`, as described below.
 
 ## Runtime debug configuration
 
@@ -112,6 +117,99 @@ Exports use `Kirie-release.aar` by default. Repository-local Android native
 debugging can opt into `Kirie-debug.aar` for a single export by passing
 `-- --kirie-android-aar=debug` to the Godot export command.
 
+## Kirie app layout and CLI direction
+
+The planned Kirie application shape is a Godot project with a Vite web frontend
+beside the Godot source:
+
+```text
+kirie.config.ts
+package.json
+pnpm-lock.yaml / bun.lock / package-lock.json
+project.godot
+src-godot/
+  main.tscn
+  main.gd or main.cs
+src-web/
+  index.html
+  src/
+  assets/
+  dist/
+addons/
+  kirie/
+  godot_cef/
+  others/
+```
+
+Directory responsibilities are:
+
+- `src-godot`: Godot host application source.
+- `src-web`: Vite web UI source and production build output.
+- `addons`: Godot plugins. Kirie remains installed as `addons/kirie`, and Godot
+  CEF remains installed as `addons/godot_cef`.
+- `kirie.config.ts`: Kirie CLI development-time configuration.
+
+Kirie does not own native platform project directories. Do not introduce
+Capacitor-style `ios/` or `android/` project trees into Kirie user projects.
+Native capabilities should be provided by Godot plugins.
+
+Kirie CLI v1 is scoped to one command:
+
+```sh
+kirie dev
+```
+
+`kirie dev` targets desktop Godot only in v1. It starts a Vite development
+server through Vite's JavaScript API, reads the actual resolved URL after Vite
+listens, launches Godot as a child process, and injects:
+
+```text
+KIRIE_DEV=1
+KIRIE_WEB_URL=http://127.0.0.1:<actual-port>/
+```
+
+The CLI does not support Finder, Dock, or other non-CLI launched macOS app
+processes. It only supports development sessions that the CLI starts and owns.
+
+Kirie CLI v1 does not implement:
+
+- `kirie create`
+- `kirie build`
+- `kirie export`
+- addon installation
+- Godot CEF installation
+- export preset management
+- BrowserWindow APIs
+
+Kirie enforces Vite as the web toolchain. Users should not hand-write a fixed
+development URL. The CLI should let Vite handle port conflicts, then pass the
+resolved URL to Godot. Advanced Vite configuration belongs under
+`web.vite` in `kirie.config.ts`; Kirie owns the base Vite invariants:
+
+```text
+root = web.root
+base = "./"
+server.host = "127.0.0.1"
+server.port = 5173
+server.strictPort = false
+server.open = false
+build.outDir = "dist"
+```
+
+User-supplied `web.vite` may extend Vite for plugins, aliases, defines, CSS,
+JSON, extra assets, proxying, headers, HMR details, Rollup options, and
+dependency optimization. It must not override Kirie-owned invariants such as
+`root`, `base`, `server.host`, `server.port`, `server.open`, or
+`build.outDir`.
+
+Future mobile development targets should use one platform command with unified
+device selection, for example `kirie dev ios --device <selector>` and
+`kirie dev android --device <selector>`. The user-facing API should not split
+iOS simulator and iOS device into separate target names. Kirie may still use
+different launch backends internally for simulators, real devices, Android
+emulators, and Android devices. Mobile development targets are explicitly out
+of scope for CLI v1.
+
 ## Packaged web resource loading
 
 `res://` web loading is scoped to resources that are exported with the
@@ -126,9 +224,13 @@ When loading `http://`, `https://`, or `file://` URLs, Kirie should keep using
 the platform WebView's default loading behavior instead of intercepting or
 rewriting those URLs.
 
-The addon export plugin currently includes `res://web` in the iOS app bundle.
-Android example exports still rely on the project export preset include filters
-for packaged web files.
+The planned Kirie CLI app layout uses `res://src-web/dist/index.html` as the
+default production entry. When that migration is implemented, the addon export
+plugin should package `res://src-web/dist` for Android and iOS exports, fail
+export when `res://src-web/dist/index.html` is missing, and drop the previous
+`res://web` behavior instead of preserving a compatibility layer. Users should
+continue to use Godot's official export preset flow; Kirie should not create or
+manage export presets.
 
 ## Desktop Godot CEF direction
 

docs/dreams/README.md

@@ -10,5 +10,6 @@ and `AGENTS.md`.
 
 Current dream notes:
 
+- [Kirie BrowserWindow](./browser-window.md)
 - [Kirie IPC Interaction TestKit](./kirie-testkit.md)
 - [Kirie Remote Debugging](./remote-debugging.md)

docs/dreams/browser-window.md

@@ -0,0 +1,60 @@
+# Kirie BrowserWindow
+
+BrowserWindow is a future high-level application API idea. It is not part of
+the current Kirie CLI or plugin milestone.
+
+## Direction
+
+Kirie's low-level primitive remains `KirieNode`: a scene-friendly owner for a
+platform WebView and IPC lanes.
+
+A future BrowserWindow layer would sit above that primitive:
+
+```text
+BrowserWindow = Godot Window + KirieNode + web entry resolver
+```
+
+The intended mental model is close to Electron's host-side window API, but the
+implementation should stay native to Godot's scene and window model. Godot's
+`Window` node owns window behavior, while `KirieNode` owns WebView creation and
+IPC.
+
+## API boundary
+
+Do not add BrowserWindow as a GDScript API. GDScript remains the low-level
+plugin substrate with `GdKirie` and `KirieNode`.
+
+Future high-level window APIs should target:
+
+- C# host-side APIs for creating and controlling windows.
+- TypeScript web-side APIs for renderer/window cooperation.
+
+This keeps the framework API in languages with package and module boundaries
+instead of expanding the addon GDScript surface.
+
+## Dependencies
+
+BrowserWindow should wait until the Kirie app layout and web entry resolver are
+stable. The planned CLI/app layout gives future window APIs a single way to
+resolve development and production entries:
+
+```text
+development: KIRIE_WEB_URL from `kirie dev`
+production: res://src-web/dist/index.html and sibling route entries
+```
+
+Until that resolver exists, users can manually compose Godot `Window` nodes and
+`KirieNode` instances in their own projects.
+
+## Out of scope
+
+Keep BrowserWindow separate from the current CLI v1 work. Do not combine it
+with:
+
+- `kirie dev`
+- the `src-godot` / `src-web` example migration
+- export plugin web-root migration
+- platform integration tests
+
+It is also not a reason to expose the full Godot CEF browser-control API through
+Kirie core.

docs/references.md

@@ -157,6 +157,14 @@ packaging, or platform WebView bridge details.
 - [Vite build guide](https://vite.dev/guide/build)
   Reference for production HTML builds used by the platform integration web
   fixture.
+- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)
+  Reference for `createServer()`, `build()`, `mergeConfig()`, and dev server
+  `resolvedUrls`, which underpin the planned `kirie dev` implementation.
+- [Vite server options](https://vite.dev/config/server-options.html)
+  Reference for development server host, port, strict port behavior, and related
+  options owned by Kirie CLI defaults.
+- [Electron BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window)
+  Comparison point for future high-level host-side browser window APIs.
 - [Electron preload scripts](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload)
   Comparison point for renderer-side runtime injection before a page is loaded.
 - [Tauri WebviewWindowBuilder initialization scripts](https://docs.rs/tauri/latest/src/tauri/webview/webview_window.rs.html)
@@ -205,3 +213,5 @@ packaging, or platform WebView bridge details.
   support, mise task configuration, and Execa.
 - When changing the platform integration web fixture, start with the Vite build
   guide and `@gd-kirie/ipc`.
+- When changing planned Kirie CLI development-server behavior, start with the
+  Vite JavaScript API and Vite server options.

examples/basic-ipc/README.md

@@ -98,6 +98,6 @@ mise run run:example -- ios basic-ipc
 
 This iOS example runner is currently simulator-only because it reuses the same
 local Godot iOS export path used by integration testing. That is a tooling
-shortcut, not a design requirement for examples. Example smoke runs should
+shortcut, not a design requirement for examples. Manual example runs should
 eventually allow the most useful local target, such as an iOS Simulator, a real
 iOS device, or an iOS app running directly on an Apple Silicon Mac.