docs

docs/quickstart.md

@@ -0,0 +1,133 @@
+# Quickstart
+
+This quickstart walks through running Cell programs, exploring examples, and creating your first module and program. It assumes the `./cell` executable is present at the repo root (already built or downloaded).
+
+## 1) Initialize a Project Shop (.cell)
+
+Create the project structure used for module management and bytecode cache:
+
+- `./cell init`
+
+This creates `.cell/` with `cell.toml`, `lock.toml`, `modules/`, `build/`, and `patches/`.
+
+## 2) Run Built‑in Examples
+
+Examples under `examples/` are programs (`*.ce`) you can run directly:
+
+- NAT portal server (introduction service):
+  - `./cell examples/nat`
+- NAT client (contacts a portal):
+  - `./cell examples/nat_client`
+- Non‑blocking HTTP download actor:
+  - `./cell examples/http_download_actor`
+
+Tip: Use these as references for portals, contacts, and non‑blocking I/O.
+
+## 3) Run the Accio Game
+
+Accio lives under `accio/`. The program is `accio/accio.ce` and supports modes via arguments:
+
+- Start menu: `./cell accio start`
+- Load a level: `./cell accio level game/1.json`
+- Analyze assets: `./cell accio analyze`
+- Clean level data: `./cell accio clean`
+
+Arguments after the program path are available inside the program via `arg` (e.g., `arg[0] == 'start'`).
+
+## 4) Your First Module (.cm) and Program (.ce)
+
+Create a module that returns a frozen API object, and a program that uses it.
+
+- File: `examples/hello.cm` (module)
+
+```javascript
+// Returns a value (frozen by the engine)
+return {
+  greet: function(name) {
+    return `Hello, ${name}!`
+  }
+}
+```
+
+- File: `examples/hello.ce` (program)
+
+```javascript
+var hello = use('examples/hello')
+
+log.console(hello.greet('Cell'))
+
+$_.receiver(function(msg) {
+  if (msg.type == 'ping') {
+    send(msg, {type:'pong'})
+  }
+})
+
+$_.delay(_ => $_.stop(), 0.1)
+```
+
+Run it:
+
+- `./cell examples/hello`
+
+Notes:
+- Modules are `*.cm` and must return a value. The engine deep‑freezes return values, so mutate via new objects or closures rather than in‑place.
+- Programs are `*.ce` and must not return a value. They run top‑to‑bottom when spawned and can register handlers via `$_.receiver()` and schedule work via `$_.delay()` or `$_.clock()`.
+
+## 5) Spawning Child Programs (Actors)
+
+Programs can spawn other programs and receive lifecycle events.
+
+- File: `examples/spawner.ce`
+
+```javascript
+$_.receiver(function(e) {
+  if (e.type == 'greet' && e.actor) {
+    log.console('Child greeted me')
+  }
+})
+
+$_.start(function(info) {
+  if (info.type == 'greet') {
+    log.console('Spawned child actor')
+  }
+}, 'examples/hello.ce')
+
+$_.delay(_ => $_.stop(), 0.5)
+```
+
+Run it:
+
+- `./cell examples/spawner`
+
+## 6) Module Shop Basics
+
+The module shop manages vendored dependencies under `.cell/modules/` and caches compiled bytecode under `.cell/build/`.
+
+Common commands (all are programs under `scripts/`):
+
+- Initialize (if you haven’t already):
+  - `./cell init`
+- See available commands:
+  - `./cell help`
+- Configure system/actor settings:
+  - `./cell config list`
+  - `./cell config set system.reply_timeout 60`
+  - `./cell config actor prosperon/_sdl_video set resolution 1280x720`
+- Download or vendor dependencies (from `.cell/cell.toml`):
+  - `./cell mod download`
+
+## 7) How Module Resolution Works
+
+- `use('path')` checks:
+  1) The current module’s directory for `path.cm` while loading.
+  2) The mounted roots (the program’s directory is mounted) for `path.cm`.
+  3) Embedded/native modules if no script file is found.
+- Modules compile to `.cell/build/<canonical-path>.o` and reuse the cache if newer than the source.
+- Scripted modules can extend embedded modules via prototype; if the script returns nothing, the embedded module is used as‑is.
+
+## 8) Next Steps
+
+- Language details: `docs/cell.md`
+- Actors, programs, and messaging: `docs/actors.md`
+- Rendering, input, and resources: `docs/rendering.md`, `docs/input.md`, `docs/resources.md`
+- Full API reference: `docs/api/`