docs(cli): flow chart for build command (#35)

Author: LemonNekoGH

AGENTS.md

@@ -1,25 +1,24 @@
 # AGENTS
 
-This repository is an experimental but intentionally reusable Godot plugin
-project.
+This repository is an experimental Godot application framework built around an
+intentionally reusable low-level WebView plugin and IPC core.
 
 ## Current Scope
 
-The current milestone is limited to:
+The low-level plugin and IPC milestone covers:
 
 1. create a platform WebView
 2. establish bidirectional IPC between Godot and the WebView
 3. support packaged `res://` web content loading enough for bridge tests
 4. add desktop Godot CEF compatibility, starting with macOS
-5. stabilize the Kirie plugin shape before adding larger tooling layers
+5. stabilize the Kirie plugin shape used by higher-level framework tooling
 
-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 exception is limited to the
-core app workflow described below: development, local build inputs,
-initialization, and diagnostics.
+Application-framework behavior belongs above the low-level plugin and IPC core.
+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 owns the app
+workflow described below: development sessions, local build inputs, export and
+run semantics, initialization, and diagnostics.
 
 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
@@ -143,7 +142,7 @@ The planned Kirie app layout is:
 - `addons/kirie/`
 - optional `addons/godot_cef/`
 
-Kirie CLI should be installed through npm and expose these planned commands:
+Kirie CLI should be installed through npm. The current foundation commands are:
 
 - `kirie dev`: start the Vite development server, launch Godot as a child
   process, and inject `KIRIE_DEV=1` and
@@ -158,9 +157,22 @@ Kirie CLI should be installed through npm and expose these planned commands:
 - `kirie doctor`: diagnose project configuration without writing files.
 - `kirie doctor --fix`: explicitly repair supported configuration problems.
 
-Keep `kirie create`, `kirie export`, and mobile dev targets outside the current
-CLI scope. These may be implemented later when explicitly planned. Future
-mobile dev targets should use a unified platform and device selector such as
+The broader app workflow should keep these command semantics:
+
+- `kirie build [--mode <mode>]`: prepare local inputs and finish. The default
+  mode is `production`; `development` and custom modes are planned but not
+  implemented yet.
+- `kirie export [--mode <mode>]`: build first, then produce a platform package.
+- `kirie run [--mode <mode>]`: build first, then directly run the scene or
+  deploy built outputs by default.
+- `kirie run --export`: explicitly export before running the exported package.
+- `kirie dev`: start the Vite hot-reload server and run a development session;
+  do not run the production web build. Desktop development can run without
+  exporting, while mobile or deploy-style development may use a development
+  export path. C#/.NET may be built when configured.
+
+Keep `kirie create` outside the current CLI scope. 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.

README.md

@@ -1,7 +1,7 @@
 # godot-kirie
 
-Kirie is an experimental Godot plugin project for embedding platform WebViews and
-building IPC between Godot and web content.
+Kirie is an experimental Godot application framework built around an embeddable
+low-level Godot WebView plugin and IPC core.
 
 ## Installation
 
@@ -70,20 +70,21 @@ example, and regression-test areas:
 
 Primary references live in [docs/references.md](docs/references.md).
 
-The first milestone is limited to:
+The low-level plugin and IPC milestone covers:
 
 1. Create a WebView on mobile and desktop platforms.
 2. Establish bidirectional IPC between Godot and the WebView.
 3. Support packaged `res://` web content loading for bridge tests.
 4. Add desktop Godot CEF compatibility, starting with macOS.
-5. Stabilize the minimum Kirie plugin shape before adding adapters and tooling.
-
-At this stage, Kirie is intended to stay a low-level WebView and IPC bridge. A
-small `@gd-kirie/ipc` browser package exists as a convenience transport wrapper.
-Eventa adapters live above that bridge: `@gd-kirie/ipc-eventa` for browser
-pages, and `GdKirie.EventaAdapter` for .NET 10 C# projects. The C# surface is a
-thin `KirieClient` wrapper over the same platform singleton used by GDScript,
-with C# events for the current Kirie signals.
+5. Stabilize the Kirie plugin shape used by higher-level framework tooling.
+
+The plugin and IPC layers are intended to stay low-level WebView and IPC
+surfaces. A small `@gd-kirie/ipc` browser package exists as a convenience
+transport wrapper. Eventa adapters live above that bridge:
+`@gd-kirie/ipc-eventa` for browser pages, and `GdKirie.EventaAdapter` for
+.NET 10 C# projects. The C# surface is a thin `KirieClient` wrapper over the
+same platform singleton used by GDScript, with C# events for the current Kirie
+signals.
 
 The mobile IPC experiment uses explicit text, binary, and data lanes over CBOR
 packets. The browser package encodes and decodes those packets with `cborg`.

docs/architecture.md

@@ -1,8 +1,11 @@
 # Architecture Notes
 
-Current repository scope is intentionally constrained.
+Kirie is evolving into an application framework with an embeddable low-level
+Godot plugin and IPC core. The repository scope is still intentionally
+constrained, but the constraint now applies to where higher-level behavior
+belongs, not to limiting the whole project to a minimum plugin shape.
 
-We are standardizing only the minimum plugin shape needed to support:
+The low-level plugin and IPC core provide:
 
 - a Godot-facing Kirie service
 - a scene-friendly KirieNode node
@@ -12,8 +15,9 @@ 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 broad application frameworks, is deferred until
-the IPC model is proven. The current `@gd-kirie/ipc` package is intentionally
+Application-framework behavior such as CLI workflows, BrowserWindow-style
+composition, routing, export orchestration, and mobile development sessions
+belongs above that core. 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.
 
@@ -154,19 +158,71 @@ 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.
 
-The planned Kirie CLI surface is intentionally small but covers the full local
-app workflow:
+The planned Kirie CLI surface is intentionally small. The current implemented
+subset covers desktop development and local build inputs:
 
 ```sh
 kirie dev
 kirie build
 kirie build web
 kirie build dotnet
+```
+
+The broader application workflow should keep these command semantics. The
+`--mode <mode>` option is planned; the current implementation does not support
+it yet:
+
+```sh
+kirie build [--mode <mode>]
+kirie export [--mode <mode>]
+kirie run [--mode <mode>] [--export]
+kirie dev
 kirie init
 kirie doctor
 kirie doctor --fix
 ```
 
+```mermaid
+flowchart TD
+    Command["User command"] --> Which{"Which command?"}
+
+    Which --> Build["kirie build\n--mode <mode>\ndefault: production"]
+    Build --> BuildInputs["Prepare local inputs"]
+    BuildInputs --> BuildDone["Finish"]
+
+    Which --> Export["kirie export\n--mode <mode>\ndefault: production"]
+    Export --> ExportBuild["Prepare local inputs"]
+    ExportBuild --> Package["Produce platform package"]
+    Package --> ExportDone["Finish"]
+
+    Which --> Run["kirie run\n--mode <mode>\ndefault: production"]
+    Run --> RunBuild["Prepare local inputs"]
+    RunBuild --> RunExport{"--export?"}
+    RunExport -->|yes| RunPackage["Produce platform package"]
+    RunPackage --> RunPackageTarget["Run exported package"]
+    RunExport -->|no| RunDirect["Direct run / deploy built outputs"]
+
+    Which --> Dev["kirie dev"]
+    Dev --> DevServer["Start Vite hot-reload server"]
+    DevServer --> DevDotnet["Build C#/.NET if configured"]
+    DevDotnet --> DevTarget{"Target requires deploy package?"}
+    DevTarget -->|desktop no| DevDesktop["Run Godot project directly"]
+    DevTarget -->|mobile/deploy yes| DevPackage["Produce development package"]
+    DevPackage --> DevDeploy["Install / launch / attach logs"]
+```
+
+In this model, `build` prepares local inputs, `export` packages those inputs,
+`run` runs or deploys the built inputs without exporting by default, and `dev`
+runs a hot-reload development session. `run --export` is the explicit form for
+exporting before running; users may also run `kirie export && kirie run` when
+they want the steps separated. `build`, `export`, and `run` default to
+`production` mode and should accept `--mode <mode>` for `development`,
+`staging`, or other user-defined modes once that option is implemented. `dev`
+should never run the production web build because it owns the Vite hot-reload
+server; desktop development can run without exporting, while mobile or
+deploy-style development may use a development export path. `dev` may still
+build the Godot C#/.NET project when one is configured.
+
 `kirie dev` starts a Vite development server, reads the actual resolved URL
 after Vite listens, launches Godot as a child process, and injects:
 
@@ -197,10 +253,13 @@ Godot C#/.NET project when one is configured or discovered. If no C# project is
 configured or discovered, the aggregate `kirie build` command may skip the
 `.NET` step; if a C# project is present, C# build failure must fail the command.
 
-`kirie export` remains future work. When it exists, it should mean a complete
-platform export workflow: build local inputs first, then call Godot's export
-flow for the selected platform or preset. It should not silently create or
-repair project configuration as part of export.
+`kirie export` and `kirie run` remain future work. `kirie export` should mean a
+complete platform export workflow: build local inputs first, then call Godot's
+export flow for the selected platform or preset. `kirie run` should build local
+inputs first, then directly run the scene or deploy the built outputs by
+default. It should only run an export workflow when the user passes
+`--export`. Neither command should silently create or repair project
+configuration.
 
 `kirie init` and `kirie doctor --fix` are the explicit commands allowed to
 write configuration. `kirie init` initializes Kirie-owned files and may register