ts2077 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,11 +1,21 @@
-# Changelog
-
-## 1.0.0
-
-First package prepared for the npm name `ts2077`. The installed commands are `ts77` and `open77-ts`.
-
-- Public CLI commands: `create`, `init`, `dev`, `build`, `watch`, `deploy`, `validate`, `doctor`, `types`, `docs`, `update`, `help`.
-- New plugins get `package.json` scripts for `dev`, `build`, `deploy`, and `validate`.
-- Optional `ts77.config.json` and `ts77.config.ts` overlay the resource config without replacing `open77-ts.json` on disk.
-- TypeScript declarations stay generated from the OPEN//77 Devkit catalogue. This release's catalogue is 2.50.0+op77.148.
-- `ts77 types` keeps the last generated declarations when the Devkit index is not on the machine, and says so.
+# Changelog
+
+## 1.0.2
+
+- The README and the guide are written for people installing the package.
+- Published files no longer include a path from the machine that generated them.
+
+## 1.0.1
+
+- `create`, `init`, and `build` write `tsconfig.json`. The editor reads that file and then the client or server project, so `@open77/sdk/client` and the native declarations resolve.
+- The npm package name is `ts2077`. The installed commands remain `ts77` and `open77-ts`.
+
+## 1.0.0
+
+First package prepared for the npm name `ts2077`. The installed commands are `ts77` and `open77-ts`.
+
+- Public CLI commands: `create`, `init`, `dev`, `build`, `watch`, `deploy`, `validate`, `doctor`, `types`, `docs`, `update`, `help`.
+- New plugins get `package.json` scripts for `dev`, `build`, `deploy`, and `validate`.
+- Optional `ts77.config.json` and `ts77.config.ts` overlay the resource config without replacing `open77-ts.json` on disk.
+- TypeScript declarations stay generated from the OPEN//77 Devkit catalogue. This release's catalogue is 2.50.0+op77.148.
+- `ts77 types` keeps the last generated declarations when the Devkit index is not on the machine, and says so.

package/README.md

@@ -1,174 +1,102 @@
-# TS77
-
-Compile OPEN//77 resources from TypeScript. Gameplay becomes Lua 5.4. A separate Node process runs backend services. React interfaces stay JavaScript inside the game's Chromium surface. Native names, parameters, and permissions come from the OPEN//77 Devkit catalogue, which in this workspace is **2.50.0+op77.148**.
-
-The long-form guide is in [docs/README.md](docs/README.md). [docs/index.html](docs/index.html) is the same guide as one page for GitHub Pages: set the site source to the `/docs` folder on the branch you publish.
-
-The server sandbox has no global `require` and no `debug` library. The compiler bundles each side into one Lua file and keeps source maps on your machine.
-
-## Requirements
-
-- Node.js 20 or newer
-- An OPEN//77 server. This repo was checked against the server at `E:\CODING\VOSS`
-- The Devkit index cache created by `npx -y @open2077/mcp init --server-dir <server>`
-
-## Install
-
-```bash
-npm install
-npm run build:tools
-```
-
-`build:tools` compiles the compiler and regenerates `packages/types/generated` from the Devkit index.
-
-## Create a plugin
-
-The npm package name is `ts2077`. The commands it installs are `ts77` and `open77-ts`.
-
-```bash
-npx ts2077 create my_plugin --template basic --no-install
-cd my_plugin
-npm install
-npm run dev
-npm run build
-```
-
-`npm run dev` watches TypeScript and rebuilds Lua. Add `--server <server-directory>` at create time, or later run `npx ts2077 deploy --server <server-directory>`, to copy the resource into that server's `resources` folder. TS77 does not reload the dedicated server.
-
-```bash
-npx open77-ts create my_resource --template basic
-npx open77-ts create my_job --template gameplay
-npx open77-ts create my_hud --template webui
-npx open77-ts create my_notes --template fullstack
-```
-
-The directory name and `open77-ts.json` `name` must match: a lowercase letter, then letters, digits, or underscores, 3 to 64 characters.
-
-```bash
-npx open77-ts build my_resource
-npx open77-ts watch my_resource
-npx open77-ts validate my_resource
-npx open77-ts doctor my_resource
-```
-
-`init` writes the basic template into an existing directory. `dev` watches TypeScript and, when `ui/` has Vite installed, starts the WebUI dev server at `http://127.0.0.1:5173/`.
-
-To copy a built resource into a server, set `serverResourcesDir` in `open77-ts.json` and run `npx open77-ts build <resource> --deploy`. Reloading a running server is a console command on that server (`reload <name>`). This CLI does not send it.
-
-## Write gameplay
-
-Client code lives in `src/client`, server code in `src/server`, and modules imported by either side in `src/shared`. Shared modules are copied into each bundle. They are not `shared_script` files and they do not call `require` at runtime.
-
-```ts
-import { emitServer, onClientResourceStart, onNet } from "@open77/sdk/client";
-import { greet } from "../shared/greeting";
-
-onClientResourceStart(() => {
-    print(greet(GetCurrentResourceName()));
-    const ok = emitServer("demo:ping", { text: "Night City" });
-    if (!ok) print("demo:ping was not sent");
-});
-```
-
-```ts
-import { authenticatedPlayer, emitClient, onNet } from "@open77/sdk/server";
-
-onNet("demo:ping", (payload) => {
-    const player = authenticatedPlayer();
-    if (player === undefined) return;
-    emitClient(player, "demo:pong", payload);
-});
-```
-
-`authenticatedPlayer()` reads the server-assigned `source`. A client cannot choose that id. Check payload fields before using them, and do not let a client grant money, items, or character changes.
-
-Natives are the real catalogue functions. `Open77.webui.create`, `TriggerServerEvent`, and `TriggerClientEvent` are called with a dot. Page methods such as `page:send` use a colon. A native that returns a value and a reason is destructured so both Lua results are kept:
-
-```ts
-const [page, reason] = Open77.webui.create({ entry: "web/index.html" });
-const [ok, failure] = TriggerClientEvent("demo:pong", playerId, payload);
-```
-
-Cursor reads `tsconfig.client.json` or `tsconfig.server.json` in the resource. Those files are rewritten on each build and point at the generated declarations, so completion follows the catalogue.
-
-A client file cannot see `TriggerClientEvent`. A server file cannot see `TriggerServerEvent`. `class`, `async`, `Promise`, `Map`, `Set`, and Node.js imports are compile errors.
-
-The build writes `open77.lua` with the Lua files that were actually produced and the permissions of the natives it found. `network.events` is added when the resource sends or receives network events. Empty script globs are not written.
-
-## React WebUI
-
-The `webui` template and `examples/hello_world` put a Vite React app in `ui/`. `npm run build` inside `ui/` writes `web/`, and the manifest lists those files one by one. The page talks to Lua through the documented bridge:
-
-```ts
-window.Open77?.on("hud:state", (payload) => render(payload));
-window.Open77?.emit("hud:ping", { text: "Night City" });
-window.Open77?.ready();
-```
-
-Lua listens with `page.on` and sends with `page.send`. For Vite during development, build with `--dev` or set the WebUI entry to `http://127.0.0.1:5173/`. That address is the player's PC. Call `Open77.ready()` again after a hot reload so Lua can send the current state.
-
-`hud` and `menu` do not need a WebUI permission. `modal`, `system`, and `debug` do, and the helper does not offer them.
-
-## Targets
-
-A resource lists the runtimes it actually builds. The defaults are client Lua, server Lua, a WebUI when `web.root` is set, and a Node companion when `backend` is set.
-
-| Target | Result |
-|---|---|
-| `open77-client` | One Lua 5.4 client bundle |
-| `open77-server` | One Lua 5.4 server bundle |
-| `node` | CommonJS from `src/backend`, run with Node.js 22 |
-| `webui` | Vite bundle from `src/webui` or `ui` |
-
-`@open77-ts/client`, `@open77-ts/server`, and `@open77-ts/shared` are compiled into Lua. `@open77-ts/shared` in gameplay is the contract module: plain values and checks, no Node APIs. `@open77-ts/node` is the companion and is rejected in a Lua or page build. `@open77-ts/webui` is the page bridge and is rejected in Lua. The older `@open77/sdk/client` and `@open77/sdk/server` names still resolve.
-
-`npx open77-ts create my_notes --template fullstack` writes `src/client`, `src/server`, `src/backend`, `src/webui`, and `src/shared`. `dev` rebuilds those targets, restarts `dist/backend/index.js` when that file exists, and starts Vite when its dependencies are installed. Set `OPEN77_BRIDGE_SECRET` in the environment before starting the companion. The game server reads the same value from the `open77_bridge_secret` convar or from that resource's tunable. Leave it empty and the server reports `bridge_secret_missing` instead of calling out.
-
-The companion listens on `127.0.0.1:11782` unless `OPEN77_BRIDGE_PORT` is set. The dedicated server must enable outbound HTTP and allow that host:
-
-```jsonc
-"http": { "enabled": true, "allowedHosts": ["127.0.0.1"] }
-```
-
-`http.allowedHosts` is a hostname, not a URL. Inbound calls from Node use `httpHandlers` and `Open77.http.listen`, which is off until the operator enables it. `OPEN77_NOTES_DRIVER` may be `memory` (the default), `mysql`, `postgres`, or `redis`. The database URL is `OPEN77_DATABASE_URL`. File reads stay inside the root configured on the companion and reject `..`.
-
-`examples/player_notes` is the full path: the React page emits `notes:submit`, client Lua sends `notes:save`, the server checks `authenticatedPlayer()` and the text, `Open77.http.request` calls `notes.save`, and the page renders the saved text or `backend_offline`. The page's health `fetch` does not save anything. Saving does not grant money, items, or vehicles. No play session in Cyberpunk 2077 was run for this example.
-
-## Debugging
-
-Type errors name the TypeScript file and line. Lua is formatted by TypeScriptToLua and carries a source map next to the bundle. The sandbox cannot run `debug.traceback`, so the map is applied by the CLI:
-
-```bash
-npx open77-ts map examples/hello_world/dist/server/main.lua 120
-```
-
-When the map has a position, the output looks like:
-
-```text
-[OPEN77-TS] Resource: hello_world
-
-Runtime Error:
-src/shared/greeting.ts:2
-```
-
-## Updating OPEN//77
-
-When a newer Devkit index is published, refresh the MCP cache and run `npm run generate` (or `npx open77-ts types`). Declarations, permissions, and reserved event prefixes are rewritten from that index. Do not hand-edit `packages/types/generated`.
-
-## Example
-
-`examples/hello_world` is a client, a server, a shared greeting module, a typed ping, and a React HUD.
-
-- The server registers `/hello` with `RegisterCommand`. Arguments arrive as strings. A console `source` of `0` is not sent to a client, because target `0` is a host error.
-- The page emits `hud:ping`. The client sends `hello:ping`. The server checks the payload and replies to `authenticatedPlayer()` with `hello:notice`.
-- The client updates the HUD with `page.send`.
-
-```bash
-npx open77-ts build examples/hello_world
-npx open77-ts validate examples/hello_world
-npm test
-```
-
-Build, Lua parse, call syntax, the `require` shim, and source-map lookup are covered by `npm test`. `open77_validate` is the Devkit's static check. Neither one replaces joining the server in Cyberpunk 2077.
-
-See [docs/limitations.md](docs/limitations.md) for the runtime restrictions and what this project does not claim.
+# TS77
+
+Write OPEN//77 plugins in TypeScript. TS77 compiles the client and the server to Lua 5.4, writes the `open77.lua` manifest, and can build a React page and an optional Node companion.
+
+The game runs the Lua. It does not run TypeScript. A web page cannot call natives. The server decides anything a player can gain.
+
+The full guide is at [imviloh.github.io/TS77](https://imviloh.github.io/TS77/).
+
+## Create a plugin
+
+You need Node.js 20 or newer. A plugin with a Node companion needs Node.js 22 for that process.
+
+```bash
+npx ts2077 create my_plugin --template basic --no-install
+cd my_plugin
+npm install
+npm run dev
+```
+
+The npm package is `ts2077`. It installs the `ts77` and `open77-ts` commands. `npm run dev` watches `src/` and rebuilds Lua when you save.
+
+Open the folder in your editor. `tsconfig.json` is already there, so `@open77/sdk/client` and the native declarations resolve.
+
+The folder name is the resource name: a lowercase letter, then letters, digits, or underscores, 3 to 64 characters. `my_plugin` is valid. `my-plugin` is not.
+
+| Template | What you get |
+|---|---|
+| `basic` | A client and a server that print a greeting. No network permission. |
+| `gameplay` | One typed event from the client to the server and back. |
+| `webui` | Gameplay plus a React page in `ui/`. |
+| `fullstack` | Gameplay, a React page, and a Node companion. |
+
+```bash
+npx ts2077 create my_job --template gameplay
+npx ts2077 create my_hud --template webui
+npx ts2077 create my_notes --template fullstack
+```
+
+## Commands
+
+Inside the plugin, `package.json` already has these scripts:
+
+```bash
+npm run dev
+npm run build
+npm run deploy
+npm run validate
+```
+
+The same actions from any directory:
+
+```bash
+npx ts2077 build my_plugin
+npx ts2077 watch my_plugin
+npx ts2077 validate my_plugin
+npx ts2077 doctor my_plugin
+```
+
+`build` writes `open77.lua`, `dist/client/main.lua`, and `dist/server/main.lua`. Leave those files alone. Change the TypeScript and build again.
+
+## Gameplay
+
+Client code is `src/client`. Server code is `src/server`. Code imported by both is `src/shared`.
+
+```ts
+import { onClientResourceStart } from "@open77/sdk/client";
+import { greet } from "../shared/greeting";
+
+onClientResourceStart(() => {
+    print(greet(GetCurrentResourceName()));
+});
+```
+
+```ts
+import { authenticatedPlayer, emitClient, onNet } from "@open77/sdk/server";
+
+onNet("demo:ping", (payload) => {
+    const player = authenticatedPlayer();
+    if (player === undefined) return;
+    emitClient(player, "demo:pong", payload);
+});
+```
+
+`authenticatedPlayer()` is the server-assigned player. A client cannot choose that id. Check the payload before you use it.
+
+Natives come from the OPEN//77 catalogue shipped with this package, **2.50.0+op77.148**. A client file cannot call `TriggerClientEvent`. A server file cannot call `TriggerServerEvent`. `class`, `async`, and Node.js imports are compile errors in gameplay.
+
+## Deploy
+
+```bash
+npx ts2077 deploy --server <server-directory>
+```
+
+`<server-directory>` is the folder that contains `server.jsonc`. TS77 copies the built resource into `resources/<plugin>` inside it. Restart that resource on the server afterward. TS77 does not reload the server.
+
+## React and Node
+
+A `webui` plugin keeps its page in `ui/`. Run `npm install` there before the first page build. The page uses `window.Open77` only: `ready`, `on`, `emit`, and `invoke`.
+
+A `fullstack` plugin adds `src/backend`. Set `OPEN77_BRIDGE_SECRET` to the same value on Node and on the game server before the companion will accept a call. Databases and other npm packages belong in that process, not in Lua.
+
+Details, the native index, and the companion protocol are in the [guide](https://imviloh.github.io/TS77/).

package/docs/README.md

@@ -1,6 +1,6 @@
 # TS77 documentation
 
-These files are the local reference for this repository. The same material is also published as one page at [index.html](index.html), which is what GitHub Pages serves when the site source is the `/docs` folder.
+The published guide is [index.html](index.html), also served at [imviloh.github.io/TS77](https://imviloh.github.io/TS77/).
 
 The catalogue this tree was generated from is **2.50.0+op77.148**. Natives, permissions, and reserved event names come from that index. They are not invented.
 
@@ -22,4 +22,4 @@ The catalogue this tree was generated from is **2.50.0+op77.148**. Natives, perm
 | [Examples](examples.md) | `hello_world` and `player_notes`, end to end |
 | [Limitations](limitations.md) | What the sandbox and this toolchain do not do |
 
-Start with [Install](install.md), then [Commands](commands.md). The player-notes walkthrough is in [Examples](examples.md).
+Plugin authors should start at the [published guide](https://imviloh.github.io/TS77/). [Install](install.md) also covers building this repository. [Commands](commands.md) lists every flag. The player-notes walkthrough is in [Examples](examples.md).

package/docs/commands.md

@@ -1,125 +1,125 @@
-# Commands
-
-The public executable is `ts77`. `open77-ts` runs the same file. The npm package name is `ts2077`.
-
-| Command | What it does |
-|---|---|
-| `ts77 create` | Writes a plugin. In a terminal with no name, it asks four questions. `--no-install` skips `npm install`. |
-| `ts77 init` | Adds the basic template to a directory and skips files that already exist. |
-| `ts77 dev` | Watches `src`, rebuilds, restarts a Node companion only when `dist/backend` exists, and starts Vite only when its dependencies are installed. |
-| `ts77 build` | Compiles the plugin. |
-| `ts77 watch` | Rebuilds on change and does not start Vite. |
-| `ts77 deploy` | Builds and copies the resource. Refuses to run until a server resources directory is set. |
-| `ts77 validate` | Checks the manifest and the Lua bundles. |
-| `ts77 doctor` | Reports Node, TypeScriptToLua, the catalogue, and the plugin layout. |
-| `ts77 types` | Regenerates declarations from the local Devkit index. |
-| `ts77 docs` | Prints the path of `docs/index.html`. `--open` opens it. |
-| `ts77 update` | Prints the catalogue build and the command that refreshes the Devkit index. It does not download or publish. |
-| `ts77 help` | Prints the command list and examples. |
-
-`ts77 --version` prints the package version. `--quiet` hides the success banner.
-
-The sections below describe the same build in more detail.
-
-The CLI is `npx ts2077` from the registry, or `npx open77-ts` from this repository. Every command except `types` and `map` takes an optional resource directory. The default is the current directory.
-
-```text
-open77-ts <command>
-
-  init [dir]
-  create <name> [--template basic|gameplay|webui|fullstack] [--out dir]
-  build [dir] [--dev] [--deploy]
-  watch [dir]
-  dev [dir]
-  validate [dir]
-  doctor [dir]
-  map <lua-file> <line> [column]
-  types
-```
-
-## init
-
-`init` copies the `basic` template into an existing directory. The directory's basename becomes the resource name and must already be a legal slug. If `open77-ts.json` is already there, the command leaves the directory alone.
-
-## create
-
-```bash
-npx open77-ts create my_resource --template basic
-npx open77-ts create my_job --template gameplay
-npx open77-ts create my_hud --template webui
-npx open77-ts create my_notes --template fullstack --out E:\CODING\VOSS\resources\my_notes
-```
-
-The destination folder name must equal `<name>`. `--out` sets that folder. Without `--out`, the folder is created in the current directory.
-
-| Template | Layout |
-|---|---|
-| `basic` | Client and server scripts that print on start. No network permission. |
-| `gameplay` | A typed ping from client to server and back. |
-| `webui` | Gameplay plus a React HUD in `ui/`. |
-| `fullstack` | `src/client`, `src/server`, `src/backend`, `src/webui`, and `src/shared`. |
-
-`__RESOURCE__` in a template is replaced with the resource name. `fullstack` still needs `npm install` inside `src/webui` before the page will build, and `OPEN77_BRIDGE_SECRET` before the companion will listen.
-
-## build
-
-```bash
-npx open77-ts build examples/player_notes
-npx open77-ts build examples/hello_world --dev
-npx open77-ts build examples/hello_world --deploy
-```
-
-For each selected target the build:
-
-1. Writes `src/generated/flags.ts` with the WebUI entry. `--dev` uses `web.devEntry` when it is set, so the page can load Vite on the player's machine.
-2. Writes `tsconfig.client.json` and `tsconfig.server.json` with paths to the SDK and the generated declarations.
-3. Rejects classes, async, Node imports, and SDK imports from the wrong runtime.
-4. Compiles client and server TypeScript to one Lua 5.4 bundle each, inlines the small TypeScriptToLua helpers, and removes the global `require` fallback. TypeScript under `src/modules` is compiled to `modules/*.lua` and listed as `file` entries for the client sandbox loader. `src/backend` is compiled with `tsc` so `require` and `import` of npm packages stay in Node.
-5. Scans the Lua for natives, refuses unknown or wrong-side calls, and records permissions.
-6. Compiles `src/backend` to `dist/backend/index.js` when the `node` target is on.
-7. Runs Vite when the `webui` target is on and `--` the WebUI dependencies are installed. A resource that lists `webui` explicitly fails the build if Vite fails. A resource that only has a `web.root` and does not list targets keeps going and prints the Vite error.
-8. Writes `open77.lua`. Scripts that were not built are omitted. `files/` and `web/` are listed file by file. Source maps are not listed.
-
-`--deploy` copies `open77.lua`, `dist`, and `web` into `<serverResourcesDir>/<resource name>`. It does not reload the server and it does not start Node. `dist/backend` is part of `dist`, so the JavaScript is copied, but the dedicated server does not execute it.
-
-## watch
-
-`watch` rebuilds when anything under `src/` changes. If `dist/backend/index.js` exists after a successful build, the previous companion process is killed and a new one is started with the current environment. The secret has to already be in that environment.
-
-## dev
-
-`dev` is `watch` plus Vite. It looks for `node_modules/vite/bin/vite.js` in `ui/` and then in `src/webui/`. The dev server binds `127.0.0.1:5173`. That address is the computer running Vite. In a real session that is the player's PC, not the dedicated server.
-
-## validate
-
-`validate` checks that every `client_script`, `server_script`, `file`, and `web_file` in `open77.lua` exists, that both Lua bundles parse, that the bundle does not fall back to the global `require`, and that the native scan still matches the catalogue. It does not typecheck TypeScript. Run `build` first.
-
-## doctor
-
-`doctor` prints `ok`, `warn`, or `fail` lines:
-
-- Node version
-- `typescript-to-lua` installed
-- Catalogue present, with its build and counts
-- A warning that the server binary may be newer than the catalogue
-- Resource name, directory name, client entry, server entry, backend entry, and target list
-- `serverResourcesDir` when it is set
-
-Exit code 1 means at least one `fail` line.
-
-## map
-
-```bash
-npx open77-ts map examples/hello_world/dist/server/main.lua 120
-npx open77-ts map examples/hello_world/dist/server/main.lua 120 4
-```
-
-Reads the `.map` beside the Lua file and prints a TypeScript file and line. Column 0 often has no mapping, so the tool also tries columns 0, 1, 2, 4, 8, and 16. The game cannot do this. `debug.traceback` is not in the sandbox, and `sourceMapTraceback` is off.
-
-## types
-
-Regenerates declarations from the Devkit index. Same as `npm run generate`.
-
-## What the CLI does not do
-
-It does not join a server, send `reload`, or open Cyberpunk 2077. Reloading a resource is a console command on that server.
+# Commands
+
+The public executable is `ts77`. `open77-ts` runs the same file. The npm package name is `ts2077`.
+
+| Command | What it does |
+|---|---|
+| `ts77 create` | Writes a plugin. In a terminal with no name, it asks four questions. `--no-install` skips `npm install`. |
+| `ts77 init` | Adds the basic template to a directory and skips files that already exist. |
+| `ts77 dev` | Watches `src`, rebuilds, restarts a Node companion only when `dist/backend` exists, and starts Vite only when its dependencies are installed. |
+| `ts77 build` | Compiles the plugin. |
+| `ts77 watch` | Rebuilds on change and does not start Vite. |
+| `ts77 deploy` | Builds and copies the resource. Refuses to run until a server resources directory is set. |
+| `ts77 validate` | Checks the manifest and the Lua bundles. |
+| `ts77 doctor` | Reports Node, TypeScriptToLua, the catalogue, and the plugin layout. |
+| `ts77 types` | Regenerates declarations from the local Devkit index. |
+| `ts77 docs` | Prints the path of `docs/index.html`. `--open` opens it. |
+| `ts77 update` | Prints the catalogue build and the command that refreshes the Devkit index. It does not download or publish. |
+| `ts77 help` | Prints the command list and examples. |
+
+`ts77 --version` prints the package version. `--quiet` hides the success banner.
+
+The sections below describe the same build in more detail.
+
+The CLI is `npx ts2077` from the registry, or `npx open77-ts` from this repository. Every command except `types` and `map` takes an optional resource directory. The default is the current directory.
+
+```text
+open77-ts <command>
+
+  init [dir]
+  create <name> [--template basic|gameplay|webui|fullstack] [--out dir]
+  build [dir] [--dev] [--deploy]
+  watch [dir]
+  dev [dir]
+  validate [dir]
+  doctor [dir]
+  map <lua-file> <line> [column]
+  types
+```
+
+## init
+
+`init` copies the `basic` template into an existing directory. The directory's basename becomes the resource name and must already be a legal slug. If `open77-ts.json` is already there, the command leaves the directory alone.
+
+## create
+
+```bash
+npx ts2077 create my_resource --template basic
+npx ts2077 create my_job --template gameplay
+npx ts2077 create my_hud --template webui
+npx ts2077 create my_notes --template fullstack --out D:\open77-server\resources\my_notes
+```
+
+The destination folder name must equal `<name>`. `--out` sets that folder. Without `--out`, the folder is created in the current directory.
+
+| Template | Layout |
+|---|---|
+| `basic` | Client and server scripts that print on start. No network permission. |
+| `gameplay` | A typed ping from client to server and back. |
+| `webui` | Gameplay plus a React HUD in `ui/`. |
+| `fullstack` | `src/client`, `src/server`, `src/backend`, `src/webui`, and `src/shared`. |
+
+`__RESOURCE__` in a template is replaced with the resource name. `fullstack` still needs `npm install` inside `src/webui` before the page will build, and `OPEN77_BRIDGE_SECRET` before the companion will listen.
+
+## build
+
+```bash
+npx open77-ts build examples/player_notes
+npx open77-ts build examples/hello_world --dev
+npx open77-ts build examples/hello_world --deploy
+```
+
+For each selected target the build:
+
+1. Writes `src/generated/flags.ts` with the WebUI entry. `--dev` uses `web.devEntry` when it is set, so the page can load Vite on the player's machine.
+2. Writes `tsconfig.json`, `tsconfig.client.json`, and `tsconfig.server.json` with paths to the SDK and the generated declarations. The editor reads `tsconfig.json`.
+3. Rejects classes, async, Node imports, and SDK imports from the wrong runtime.
+4. Compiles client and server TypeScript to one Lua 5.4 bundle each, inlines the small TypeScriptToLua helpers, and removes the global `require` fallback. TypeScript under `src/modules` is compiled to `modules/*.lua` and listed as `file` entries for the client sandbox loader. `src/backend` is compiled with `tsc` so `require` and `import` of npm packages stay in Node.
+5. Scans the Lua for natives, refuses unknown or wrong-side calls, and records permissions.
+6. Compiles `src/backend` to `dist/backend/index.js` when the `node` target is on.
+7. Runs Vite when the `webui` target is on and `--` the WebUI dependencies are installed. A resource that lists `webui` explicitly fails the build if Vite fails. A resource that only has a `web.root` and does not list targets keeps going and prints the Vite error.
+8. Writes `open77.lua`. Scripts that were not built are omitted. `files/` and `web/` are listed file by file. Source maps are not listed.
+
+`--deploy` copies `open77.lua`, `dist`, and `web` into `<serverResourcesDir>/<resource name>`. It does not reload the server and it does not start Node. `dist/backend` is part of `dist`, so the JavaScript is copied, but the dedicated server does not execute it.
+
+## watch
+
+`watch` rebuilds when anything under `src/` changes. If `dist/backend/index.js` exists after a successful build, the previous companion process is killed and a new one is started with the current environment. The secret has to already be in that environment.
+
+## dev
+
+`dev` is `watch` plus Vite. It looks for `node_modules/vite/bin/vite.js` in `ui/` and then in `src/webui/`. The dev server binds `127.0.0.1:5173`. That address is the computer running Vite. In a real session that is the player's PC, not the dedicated server.
+
+## validate
+
+`validate` checks that every `client_script`, `server_script`, `file`, and `web_file` in `open77.lua` exists, that both Lua bundles parse, that the bundle does not fall back to the global `require`, and that the native scan still matches the catalogue. It does not typecheck TypeScript. Run `build` first.
+
+## doctor
+
+`doctor` prints `ok`, `warn`, or `fail` lines:
+
+- Node version
+- `typescript-to-lua` installed
+- Catalogue present, with its build and counts
+- A warning that the server binary may be newer than the catalogue
+- Resource name, directory name, client entry, server entry, backend entry, and target list
+- `serverResourcesDir` when it is set
+
+Exit code 1 means at least one `fail` line.
+
+## map
+
+```bash
+npx open77-ts map examples/hello_world/dist/server/main.lua 120
+npx open77-ts map examples/hello_world/dist/server/main.lua 120 4
+```
+
+Reads the `.map` beside the Lua file and prints a TypeScript file and line. Column 0 often has no mapping, so the tool also tries columns 0, 1, 2, 4, 8, and 16. The game cannot do this. `debug.traceback` is not in the sandbox, and `sourceMapTraceback` is off.
+
+## types
+
+Regenerates declarations from the Devkit index. Same as `npm run generate`.
+
+## What the CLI does not do
+
+It does not join a server, send `reload`, or open Cyberpunk 2077. Reloading a resource is a console command on that server.