# Learn Gizlang
> **Purpose:** Choose a learning path, then run source-backed examples and complete labs.
> **Repository:** `gizlang:main`, `gizstack:main`
> **Language:** English
This page is the learning layer over the canonical documentation. It starts with a platform tour, then gives role-based paths and complete labs. It does not duplicate language, SQL, web, database or runtime references. The ownership rules are in [`DOCUMENTATION.md`](DOCUMENTATION.md).
## Fast path
1. [Quickstart](quickstart.md)
2. [Platform tour](#platform-tour)
3. [Language guide](guides/language.md)
4. [Command line](guides/command-line.md)
5. [Todo application lab](labs/todo-app.md)
6. [Agent SDK](guides/agent.md) and [GizDesk lab](labs/gizdesk.md)
## Choose a path
| You are here | Read in this order | You will finish with |
| --- | --- | --- |
| New to Gizlang | [Quickstart](quickstart.md) → [Platform tour](#platform-tour) → [Language guide](guides/language.md) | A typed native program |
| A TypeScript developer | [Quickstart](quickstart.md) → [TypeScript differences](reference/typescript.md) → [Language guide](guides/language.md) | Familiar syntax with native builds |
| Building an application | [Quickstart](quickstart.md) → [Models](guides/model.md) → [Data access](guides/data-access.md) → [GizWeb](guides/web.md) → [Todo lab](labs/todo-app.md) | A tested web application |
| Building an AI system | [Quickstart](quickstart.md) → [Compute](guides/compute.md) → [Agent SDK](guides/agent.md) → [GizDesk lab](labs/gizdesk.md) | A model-backed agent |
| Operating the platform | [GizDB server](guides/gizdb-server.md) → [Storage range](guides/storage-range.md) → [Benchmarks](operations/benchmarks.md) | An evidence-backed deployment |
| Contributing to the runtime | [Language reference](reference/language.md) → [Compiler internals](internals/compiler.md) → [Runtime internals](internals/runtime.md) → [Performance](internals/performance.md) | A source-level change with proof |
Each path names a result and points to the owner of each fact. Use the guides for procedures, references for exact rules, and internals for implementation decisions.
## Volumes
### Volume 1: Language and tooling
Read [the language reference](reference/language.md), [the language guide](guides/language.md), [the command-line
guide](guides/command-line.md), [compiler internals](internals/compiler.md), [tools internals](internals/tools.md),
and the [runtime and system contracts](internals/runtime.md).
### Volume 2: Application engineering
Read [models](guides/model.md), [data access](guides/data-access.md), and [GizWeb](guides/web.md), then complete
the [real-time Todo lab](labs/todo-app.md).
### Volume 3: GizDB {#volume-3-gizdb}
Read [GizDB](guides/data.md), [data access](guides/data-access.md), [vector search](guides/vector.md),
[server operations](guides/gizdb-server.md), [SQL](reference/sql.md), and [database internals](internals/database.md).
### Volume 4: Agents and generative systems
Read [Agents](guides/agent.md) and [GizDesk](guides/desk.md), then complete the [GizDesk workspace lab](labs/gizdesk.md).
### Volume 5: Machine learning and hardware {#volume-5-machine-learning-and-hardware}
Read [compute](guides/compute.md), [machine learning](guides/ml.md), [hardware](guides/hardware.md),
[compute internals](internals/compute.md), and [SQL ML](internals/sql-ml.md).
### Volume 6: Systems and platform {#volume-6-systems-and-platform}
Read [compiler](internals/compiler.md), [runtime](internals/runtime.md), [memory](internals/memory.md),
[system](internals/system.md), [VM](internals/vm.md), [tools](internals/tools.md), [storage](internals/storage.md),
and [localization](internals/localization.md).
### Volume 7: Operations and benchmark proof
Use [the benchmark record](operations/benchmarks.md), [performance rules](internals/performance.md), and [the release
history](operations/changelog.md).
## Example catalog
The tour examples are deliberately small. Use these complete examples when you need a realistic starting point:
| Example | What to inspect | Follow-up |
| --- | --- | --- |
| [`examples/cli/wordcount.giz`](../examples/cli/wordcount.giz) | Files, maps, errors and exit codes | [Command line guide](guides/command-line.md) |
| [`examples/cli/orders.giz`](../examples/cli/orders.giz) | A model-backed command-line workflow | [Model guide](guides/model.md) |
| [`examples/web/notes`](../examples/web/notes/) | Routes, forms, database access and tests | [GizWeb guide](guides/web.md) |
| [`examples/web/admin`](../examples/web/admin/) | Generated pages and data policies | [Data access guide](guides/data-access.md) |
| [`examples/todo`](../examples/todo/) | A small live application | [Todo lab](labs/todo-app.md) |
| [`examples/ml`](../examples/ml/) | Datasets, experiments and standalone inference | [Machine learning guide](guides/ml.md) |
| [`examples/tour`](../examples/tour/) | One program per platform subsystem | [Platform tour](#platform-tour) |
Every example is source code in the repository. A documentation snippet is complete only when the docs test can check or run it; hardware, model downloads and external-service examples identify their separate prerequisites.
## 📸 Empirical Visual Screenshot Catalog
This page includes 23 live screenshots captured directly from running daemons and headless Chrome CDP sessions. Every
`gizdesk-*.png` is captured from a running Desk; the base catalog uses `giz run tools/browser/guidebook.giz BASE docs/images/guidebook`, and sample-state captures use `agent-browser` after loading synthetic data
([GizDesk lab](labs/gizdesk.md#retaking-the-screenshots)):
| Image File | Description | Owning Chapter |
| :--- | :--- | :--- |
| [`todo-app-initial.png`](images/guidebook/todo-app-initial.png) | Fresh Todo app with empty list and auto-provisioned DDL | [Todo lab](labs/todo-app.md) |
| [`todo-app-active.png`](images/guidebook/todo-app-active.png) | Collaborative Todo app with multiple tasks, drafts, and completed badges | [Todo lab](labs/todo-app.md) |
| [`gizdesk-connections.png`](images/guidebook/gizdesk-connections.png) | GizDesk model accounts, quota state, and rotation order | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-computers.png`](images/guidebook/gizdesk-computers.png) | GizDesk computers the agent works on, each command approval-gated | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive.png`](images/guidebook/gizdesk-drive.png) | The Desk's own Drive with a Markdown file open, its tags and comments | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-grid.png`](images/guidebook/gizdesk-drive-grid.png) | Drive folders as tiles | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-search.png`](images/guidebook/gizdesk-drive-search.png) | Drive search across names and contents | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-share.png`](images/guidebook/gizdesk-drive-share.png) | Drive share dialog: invitations, a link's role, password and expiry | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-link.png`](images/guidebook/gizdesk-drive-link.png) | A share link's page, served by the Desk without an account | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-activity.png`](images/guidebook/gizdesk-drive-activity.png) | Drive activity: every change through the app, the API and agents | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-phone.png`](images/guidebook/gizdesk-drive-phone.png) | Drive on a phone | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-s3.png`](images/guidebook/gizdesk-drive-s3.png) | Drive S3 access: the endpoint, bucket and access keys for any S3 client | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-services.png`](images/guidebook/gizdesk-services.png) | Connections Services: the mailer and the office engine you run | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-drive-office.png`](images/guidebook/gizdesk-drive-office.png) | A document preview offering Edit in Office through the connected engine | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-data-studio.png`](images/guidebook/gizdesk-data-studio.png) | Data Studio with sample sales data, schema, query results and export | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-data-studio-chart.png`](images/guidebook/gizdesk-data-studio-chart.png) | Data Studio sample sales chart | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-metrics-catalog.png`](images/guidebook/gizdesk-metrics-catalog.png) | Governed metric catalog with reusable query definition | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-data-builder.png`](images/guidebook/gizdesk-data-builder.png) | Approval-gated no-code collection builder | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-ml.png`](images/guidebook/gizdesk-ml.png) | Data & ML completed regression comparison and deployment approval | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-workspace.png`](images/guidebook/gizdesk-workspace.png) | GizDesk conversation and workspace overview | [GizDesk lab](labs/gizdesk.md) |
| [`gizdesk-knowledge-panel.png`](images/guidebook/gizdesk-knowledge-panel.png) | GizDesk agent knowledge, skills and MCP connections | [GizDesk lab](labs/gizdesk.md) |
| [`gizai-agent-plugins-tools.png`](images/guidebook/gizai-agent-plugins-tools.png) | GizDesk agent editor and MCP plugin configuration | [GizDesk lab](labs/gizdesk.md) |
---
## Platform tour
Each section below is a small, runnable example. The source files live under `examples/tour` and the documentation test checks their output.
## The language
Types are checked when you compile. A union of object types is narrowed by its `kind`, and an error is thrown and
caught as in TypeScript.
```typescript gizlang run file="examples/tour/hello.giz"
// The language: TypeScript compiled to native code. Types, unions, switch and exceptions.
type Shape = { kind: "circle"; r: number } | { kind: "square"; side: number };
function area(s: Shape): number {
switch (s.kind) {
case "circle": return Math.PI * s.r * s.r;
case "square": return s.side * s.side;
}
}
function half(n: number): number {
if (n % 2 !== 0) throw new Error(`${n} is odd`);
return n / 2;
}
function main(): void {
const shapes: Shape[] = [{ kind: "circle", r: 1 }, { kind: "square", side: 2 }];
for (const s of shapes) console.log(`area ${area(s).toFixed(2)}`);
for (const n of [12, 6]) {
try {
console.log(`${n} / 4 = ${half(half(n))}`);
} catch (e) {
console.log(`${n}: ${e.message}`);
}
}
}
```
```text output
area 3.14
area 4.00
12 / 4 = 3
6: 3 is odd
```
Next: [the language guide](guides/language.md), and [the differences from TypeScript](reference/typescript.md).
## Tasks
`Task.parallel` runs a body on each core, and gives the results in index order. The standard library (`gizlang:`)
also has threads, channels, timers and async I/O.
```typescript gizlang run file="examples/tour/tasks.giz"
// Tasks: Task.parallel runs a body on every core and gives the results in order.
import * as Task from "gizlang:task";
function main(): void {
const squares = Task.parallel(8, (i: i64): i64 => { return i * i; });
let sum = 0;
for (const s of squares) { sum += s; }
print(`${squares.map((s: i64): string => { return string(s); }).join(" ")} sum ${sum}`);
}
```
```text output
0 1 4 9 16 25 36 49 sum 140
```
Next: [the standard library reference](https://gizstack.com/docs/reference/sdk).
## GizDB
GizDB is a database in your program: a folder, SQL with parameters, transactions, and no server to run. The same
engine is also a server that PostgreSQL clients use.
```typescript gizlang file="examples/tour/data.giz"
// GizDB in the program: a database in a folder, SQL with parameters, no server.
import {System} from "gizlang:system";
import * as Embedded from "gizdb:embedded";
function main(sys: System): void {
const folder = sys.temporaryDir();
const db = Embedded.open(sys, folder.temporaryPath());
db.exec("CREATE TABLE notes (id INT PRIMARY KEY, title TEXT, stars INT)");
db.query("INSERT INTO notes VALUES ($1, $2, $3)", ["1", "Buy milk", "2"]);
db.query("INSERT INTO notes VALUES ($1, $2, $3)", ["2", "Write the tour", "5"]);
for (const row of db.query("SELECT title, stars FROM notes WHERE stars > $1", ["3"]).rows) {
print(`${row[0] ?? ""} ${row[1] ?? ""}`);
}
db.close();
}
```
```text output
Write the tour 5
```
Next: [use GizDB](guides/data.md), [model your data](guides/model.md),
[access external databases](guides/data-access.md), [vector search](guides/vector.md),
[machine learning in SQL](guides/ml.md), [run the GizDB server](guides/gizdb-server.md).
## GizWeb
A GizWeb site can be a folder of pages: each `.ghtml`, `.md` and `.html` file under `pages/` is an address. A `.ghtml`
file is HTML with Gizlang in braces. This is `examples/web/pages`:
```typescript gizlang file="examples/web/pages/main.giz"
// A site from files, like PHP or Next.js: every .ghtml, .md and .html file of pages/ is an address (docs/reference/ghtml.md).
// Run: giz examples/web/pages/main.giz, then open http://127.0.0.1:8080
import {System} from "gizlang:system";
import * as Web from "gizweb";
import * as Pages from "gizweb:pages";
import {site} from "./pages/.routes";
function main(sys: System): i64 {
return Web.listen(
sys,
8080,
Pages.shell(""),
Web.serving(),
(own: System) => Pages.handler(site(), Pages.shell(""), Pages.standalone(own))
);
}
```
```html file="examples/web/pages/pages/blog/[slug].ghtml"
Post: {slug}
All posts
```
`giz examples/web/pages/main.giz` serves it at `http://127.0.0.1:8080`, and `/blog/hello` shows "Post: hello".
Next: [build a web app](guides/web.md), where one model gives the table, the form, the checks and the API.
## Compute
`gizai` has tensors, fused elementwise chains, gradients and models. The same calls run on a GPU when the machine has
one.
```typescript gizlang run file="examples/tour/tensors.giz"
// gizai: tensors on the CPU, or on a GPU when the machine has one.
import * as TensorCore from "gizai:tensor/core";
function main(): void {
const a = TensorCore.tensor([2, 3], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
const b = TensorCore.tensor([3, 2], [1.0, 0.0, 0.0, 1.0, 1.0, 1.0]);
print(a.matmul(b).text());
}
```
```text output
[[4, 5], [10, 11]]
```
Next: [tensors, GPU kernels and gradients](guides/compute.md).
## Storage
`gizfs` keeps buckets and objects. Here it is embedded in the program; the same calls reach a range of machines or
gizstack.com.
```typescript gizlang file="examples/tour/storage.giz"
// gizfs: buckets and objects, here in an embedded store in a folder.
import {System} from "gizlang:system";
import {embedded} from "gizfs:node";
import * as Object from "gizfs:object";
function main(sys: System): void {
const folder = sys.temporaryDir()!;
const store = embedded(sys, folder.temporaryPath()!, "me").unwrap();
store.changeObject(Object.Command.bucket("me", "photos", false)).unwrap();
store.put("photos", "2026/hello.txt", utf8("Hello"), "text/plain").unwrap();
print(string(store.get("photos", "2026/hello.txt", 0).unwrap()));
store.close();
}
```
```text output
Hello
```
Next: [use storage](guides/storage.md), [run a storage range](guides/storage-range.md).
## Devices
`gizhw` reads and drives the machine: GPUs, NPUs, cameras, audio, video codecs and sensors. This program prints the
platform and each sensor that the operating system shows, so its output is that of your machine.
```typescript gizlang file="examples/tour/devices.giz"
// gizhw: the machine's devices and sensors, read from the operating system.
import {System} from "gizlang:system";
import * as Device from "gizhw:device";
function main(sys: System): void {
print(Device.platform(sys));
for (const s of Device.sensors(sys).valueOr([])) { print(`${s.device} ${s.channel} ${s.value}`); }
}
```
Next: [hardware and devices](guides/hardware.md), [compute on the GPU](guides/compute.md#step-2-the-same-work-on-a-gpu).
## AI models
`gizai:ai` runs models by name on your machine: chat and embeddings; `gizai:tasks/image` and `gizai:tasks/video` make images and videos, `gizai:studio` holds an app's models, and `gizai:serve` is an OpenAI-compatible server. The
first use downloads the weights.
```sh
giz ai chat qwen3.5-4b "Name three rivers."
```
Next: [compute and generative AI](guides/compute.md), [classical ML](guides/ml.md),
[typed agent tools](guides/agent.md) and the [GizDesk application](guides/desk.md).
## JavaScript and Python
The `giz` command also runs JavaScript, TypeScript and Python on the Gizlang VM, with npm packages, Node's modules and
Python's standard library.
```typescript file="examples/tour/hello.ts"
// TypeScript on the Gizlang VM: Node's modules work, with no Node.js installed.
import { createHash } from "node:crypto";
const words: string[] = "the cat and the dog".split(" ");
const counts = new Map();
for (const w of words) counts.set(w, (counts.get(w) ?? 0) + 1);
console.log([...counts].map(([w, n]) => `${w}=${n}`).join(" "));
console.log(createHash("sha256").update("gizlang").digest("hex").slice(0, 16));
```
```text output
the=2 cat=1 and=1 dog=1
db69adfa269a71dd
```
```python file="examples/tour/hello.py"
# Python on the Gizlang VM: the program runs in the VM's interpreter and JIT.
import json
counts = {}
for word in "the cat and the dog".split():
counts[word] = counts.get(word, 0) + 1
print(json.dumps(counts, sort_keys=True))
```
```text output
{"and": 1, "cat": 1, "dog": 1, "the": 2}
```
Next: [JavaScript, TypeScript and Python](guides/javascript-python.md).
## More programs
| Program | Shows |
| --- | --- |
| `examples/cli/wordcount.giz` | A command-line tool: files, `throws` and `try`/`catch`, maps and the exit code |
| `examples/cli/orders.giz` | One record type gives the DDL, the form checks, the rows and the JSON ([model your data](guides/model.md)) |
| `examples/web/http` | A server-rendered app on `gizlang:http` alone: routes, markup components and a form |
| `examples/web/notes` | The same app on GizWeb, with unit tests and a journey test ([build a web app](guides/web.md)) |
| `examples/web/admin` | An admin app from one annotated record type, with no page or action written |