finish up docs

docs/guide/astal-cli.md

@@ -1,3 +1,86 @@
 # Astal CLI
 
-🚧 WIP 🚧
+AGS provides aliases for the [Astal CLI](https://aylur.github.io/astal/guide/typescript/cli-app).
+
+## [Request](https://aylur.github.io/astal/guide/typescript/cli-app#messaging-from-cli)
+
+```ts
+App.start({
+    requestHandler(request: string, res: (response: any) => void) {
+        if (request == "say hi") {
+            res("hi cli")
+        }
+        res("unknown command")
+    },
+})
+```
+
+:::code-group
+
+```sh [astal]
+astal say hi --instance astal
+# hi cli
+```
+
+```sh [ags]
+ags request "say hi" --instance astal
+# hi cli
+```
+
+:::
+
+## List
+
+:::code-group
+
+```sh [astal]
+astal --list
+```
+
+```sh [ags]
+ags list
+```
+
+:::
+
+## [Opening the inspector](https://aylur.github.io/astal/guide/typescript/theming#inspector)
+
+:::code-group
+
+```sh [astal]
+astal --inspector --instance astal
+```
+
+```sh [ags]
+ags inspect --instance astal
+```
+
+:::
+
+## [Window toggling](https://aylur.github.io/astal/guide/typescript/cli-app#toggling-windows-by-their-name)
+
+:::code-group
+
+```sh [astal]
+astal --toggle-window window-name --instance astal
+```
+
+```sh [ags]
+ags toggle window-name --instance astal
+```
+
+:::
+
+## Quitting App
+
+:::code-group
+
+```sh [astal]
+astal --quit --instance astal
+```
+
+```sh [ags]
+ags quit --instance astal
+```
+
+:::

docs/guide/bundling.md

@@ -0,0 +1,108 @@
+# Bundling projects
+
+Bundling can be done with the `ags bundle` command.
+
+:::details
+Uses [esbuild](https://esbuild.github.io/) under the hood.
+:::
+
+```sh
+$ ags bundle --help
+
+Bundle an app
+
+Usage:
+  ags bundle [entryfile] [outfile] [flags]
+
+Flags:
+  -h, --help              help for bundle
+      --src string        source directory of the bundle
+      --tsconfig string   path to tsconfig.json
+```
+
+Currently there are 3 builtin plugins.
+
+- css: import `.css` will be inlined as a string
+- sass: importing `.scss` files will go through the sass transpiler and be inlined as a string that contains valid css
+  - uses the `sass` executable found on $PATH
+- blp: importing `.blp` files will go through [blueprint](https://jwestman.pages.gitlab.gnome.org/blueprint-compiler/) and be inlined as a string that contains valid xml template definitions
+
+AGS also defines a global `SRC` variable which will be replaced by the value of the `--src` flag.
+By default it will point to the directory of `entryfile`.
+
+```js
+#!/usr/bin/ags run
+App.start({
+    main() {
+        print(`source dir is ${SRC}`)
+    }
+})
+```
+
+By default `ags bundle` will look for a `tsconfig.json` in the root directory,
+read it and update it internally so that `paths` and `jsxImportSource` points to
+the correct location of the Astal js package.
+This behavior can be altered by using the `--tsconfig` flag which won't be
+updated internally and will use the paths defined in it.
+
+## Example
+
+:::code-group
+
+```blp [Bar.blp]
+using Gtk 4.0;
+using Astal 4.0;
+
+template $Bar: Astal.Window {
+    // bitfields currently don't work in blueprint
+    // anchor: top | left | right;
+    exclusivity: exclusive;
+
+    CenterBox {
+        center-widget: Label {
+            label: "hello";
+        };
+    }
+}
+```
+
+:::
+
+:::code-group
+
+```ts [app.ts]
+#!/usr/bin/gjs -m
+import { register } from "astal/gobject"
+import { App, Astal } from "astal/gtk4"
+import Template from "./Bar.blp"
+
+const { TOP, LEFT, RIGHT } = Astal.WindowAnchor
+
+@register({ GTypeName: "Bar", Template })
+class Bar extends Astal.Window {
+}
+
+App.start({
+    instanceName: "bar",
+    main() {
+        new Bar({
+            application: App,
+            anchor: TOP | LEFT | RIGHT,
+            visible: true,
+        })
+    }
+})
+```
+
+:::
+
+```sh
+ags bundle ./app.ts bar
+chmod +x ./bar
+
+./bar
+```
+
+> [!NOTE]
+> On Nix this still has to be done in a derivation
+> as the bundled script is not wrapped.

docs/guide/example.md

@@ -0,0 +1,101 @@
+# Dialog Example
+
+Simple dialog example to get a `no`/`yes` answer.
+
+![2024-11-13_00-45-58](https://github.com/user-attachments/assets/73a20155-fa0e-4156-aff8-3a0d055abb9b)
+
+```tsx
+#!/usr/bin/ags run
+import { App, Astal, Gtk, Gdk } from "astal/gtk3"
+
+const { TOP, BOTTOM, LEFT, RIGHT } = Astal.WindowAnchor
+const { IGNORE } = Astal.Exclusivity
+const { EXCLUSIVE } = Astal.Keymode
+const { CENTER } = Gtk.Align
+
+App.start({
+    instanceName: "tmp" + Date.now(),
+    gtkTheme: "adw-gtk3-dark",
+    css: /* css */`
+        window {
+            all: unset;
+            background-color: alpha(black, 0.3);
+        }
+
+        window > box {
+            margin: 10px;
+            padding: 6px;
+            box-shadow: 2px 3px 5px 0 alpha(black, 0.6);
+            border-radius: 11px;
+            background-color: #181818;
+            color: white;
+            min-width: 200px;
+        }
+
+        box > label {
+            font-size: large;
+            margin: 6px;
+        }
+
+        label.title {
+            font-size: 1.4em;
+        }
+
+        .action {
+            color: alpha(white, 0.8);
+        }
+
+        button {
+            margin: 6px;
+        }
+    `,
+    main: (action = "XYZ") => {
+        function yes() {
+            print("yes")
+            App.quit()
+        }
+
+        function no() {
+            print("no")
+            App.quit()
+        }
+
+        function onKeyPress(_: Astal.Window, event: Gdk.Event) {
+            if (event.get_keyval()[1] === Gdk.KEY_Escape) {
+                no()
+            }
+        }
+
+        <window
+            onKeyPressEvent={onKeyPress}
+            exclusivity={IGNORE}
+            keymode={EXCLUSIVE}
+            anchor={TOP | BOTTOM | LEFT | RIGHT}>
+            <box halign={CENTER} valign={CENTER} vertical>
+                <label className="title" label="Are you sure you want to do" />
+                <label className="action" label={`${action}?`} />
+                <box homogeneous>
+                    <button onClicked={yes}>
+                        Yes
+                    </button>
+                    <button onClicked={no}>
+                        No
+                    </button>
+                </box>
+            </box>
+        </window>
+    }
+})
+```
+
+Then it can be used in any script.
+
+```sh
+if [[ "$(script -a Shutdown)" == "yes" ]]; then
+    shutdown now
+fi
+```
+
+> [!TIP]
+> If you are happy with the script and don't plan to change it anymore [bundle](./bundling.md) it,
+> which will remove the dependency on AGS.

docs/guide/init.md

@@ -1,3 +1,84 @@
 # Setting up a project
 
-🚧 WIP 🚧
+You can initalize a project with the `init` command.
+
+```sh
+$ ags init --help
+
+Initialize a project directory by setting up files needed by TypeScript,
+generating types and setting up a basic bar example
+
+Usage:
+  ags init [flags]
+
+Flags:
+  -d, --directory string   target directory (default "/home/demeter/.config/ags")
+  -f, --force              override existing files
+  -g, --gtk int            gtk version to use (default 3)
+  -h, --help               help for init
+
+```
+
+By default it will set it up at `$HOME/.config/ags`,
+but you can specify the target directory with the `-d` flag.
+
+It will generate the following files:
+
+```txt
+.
+├── .gitignore
+├── @girs/              # generated types
+├── widget/
+│   └── Bar.tsx
+├── app.ts              # entry proint
+├── env.d.ts            # additional types
+├── style.scss
+└── tsconfig.json       # needed by LSPs
+```
+
+The `@girs` directory contains the generated types, which are
+created when running the `init` command or the `types` command.
+
+Assuming this directory will be tracked with git,
+it generates a `.gitignore` file which is set to ignore `@girs` and `node_modules`.
+Initially `node_modules` doesn't exist, but if you decide to install any `npm`
+package it is not needed to track them with git. You can also add `tsconfig.json`
+and `env.d.ts` to this list, as they are only used for developing and can be
+regenerated with the `types` command. Only track `tsconfig.json` if you add
+anything additional to `compilerOptions.paths`.
+
+> [!NOTE]
+> Since the runtime is `gjs`, very few packages will run from `npm`.
+
+The `env.d.ts` will tell the LSP that `.css`, `.scss` and `.blp` files can be
+imported and will be inlined as a string. It also tells it that imports
+prefixed with `inline:` will be inlined as well as that a global `SRC` variable
+is available.
+
+The `tsconfig.json` file tells information to the LSP so that
+intellisense can do its thing and provide great DX.
+
+`app.ts` is the entry point of the project which usually contains only
+an `App.start` call where you define [main](https://aylur.github.io/astal/guide/typescript/cli-app#entry-point) and [requestHandler](https://aylur.github.io/astal/guide/typescript/cli-app#messaging-from-cli),
+but can contain any other code.
+
+> [!NOTE]
+> You could also name the entry file `app.tsx` and write any JSX there.
+
+> [!TIP]
+> You are not forced to use TypeScript. Adding `"allowJs": true`
+> in `tsconfig.json` and optionally `"checkJs": true` will allow
+> JavaScript, although it is very much recommended to TypeScript.
+
+You are not forced into a project structure. You can put
+`style.scss` and `widget/Bar.ts` anywhere you like, only the entry file matters.
+
+## Running projects
+
+`tsconfig.json`, `env.d.ts` and `@girs` are only significant for the LSP,
+they are not needed to run the project.
+
+:::tip
+You can also use `ags run` as a shebang line for simple scripts.
+See an [simple dialog example](./example.md)
+:::