4 files changed, 54 insertions, 24 deletions
diff --git a/docs/guide/getting-started/installation.md b/docs/guide/getting-started/installation.md
index af82cf5..6ad951a 100644
--- a/docs/guide/getting-started/installation.md
+++ b/docs/guide/getting-started/installation.md
@@ -10,6 +10,8 @@ Read more about it on the [nix page](./nix#astal)
 
 maintainer: [@kotontrion](https://github.com/kotontrion)
 
+<!--TODO: fix aur package names-->
+
 :::code-group
 
 ```sh [Core Library]
@@ -28,7 +30,6 @@ yay -S libastal-meta
 
 ```sh
 git clone https://github.com/aylur/astal.git
-cd astal/core
 ```
 
 2. Install the following dependencies
@@ -51,7 +52,18 @@ sudo apt install meson valac libgtk-3-dev libgtk-layer-shell-dev gobject-introsp
 
 3. Build and install with `meson`
 
+- astal-io
+
+```sh
+cd lib/astal/io
+meson setup build
+meson install -C build
+```
+
+- astal3
+
 ```sh
+cd lib/astal/gtk3
 meson setup build
 meson install -C build
 ```
diff --git a/docs/guide/getting-started/introduction.md b/docs/guide/getting-started/introduction.md
index 92d2ff1..af176c3 100644
--- a/docs/guide/getting-started/introduction.md
+++ b/docs/guide/getting-started/introduction.md
@@ -2,22 +2,25 @@
 
 ## What is Astal?
 
-Astal (_meaning "desk"_) is a bundle of libraries built using [GLib](https://docs.gtk.org/glib/) in Vala and C.
-The core library [libastal](https://aylur.github.io/libastal) has some Gtk widgets that come packaged,
-the most important one is the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell).
+Astal (_meaning "desk"_) is a suite of libraries in Vala and C.
+The core library [astal3](https://aylur.github.io/libastal/astal3) and
+[astal4](https://aylur.github.io/libastal/astal4) (not yet available)
+has some Gtk widgets that come packaged,
+the most important one being the [Window](https://aylur.github.io/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell).
 This is what allows us to use Gtk as shell components on Wayland.
-libastal also comes with some utility functions such as running external processes,
-reading, writing and monitoring files.
+The other part of the core library [astal-io](https://aylur.github.io/libastal/astal-io)
+which contains some utility GLib shortcut for running external processes,
+reading, writing and monitoring files, timeout and interval functions.
 
 ## Why Astal?
 
-What makes Astal convenient to use is not the core library, as it could easily be replaced
+What makes Astal convenient to use is not the core libraries, as they can easily be replaced
 by the standard library of any of your favorite language that has bindings to Gtk, it is the
-accompanying libraries (_formerly known as "services" in AGS_)
+accompanying libraries (_formerly known as "services" in AGS_).
 
 Have you ever wanted to write a custom bar, custom notification popups
 or an applauncher, but gave up because writing a workspace widget,
 implementing the notification daemon or handling a search filter was too much of a hassle?
 
-Astal libraries have you [covered](/guide/libraries/references), you don't have to worry about these,
+Astal libraries have you [covered](../libraries/references#astal-libraries), you don't have to worry about these,
 you just define the layout, style it with CSS and that's it.
diff --git a/docs/guide/getting-started/nix.md b/docs/guide/getting-started/nix.md
index 81f4e4d..5c0db28 100644
--- a/docs/guide/getting-started/nix.md
+++ b/docs/guide/getting-started/nix.md
@@ -1,3 +1,8 @@
+---
+next:
+  link: '/guide/getting-started/supported-languages'
+  text: 'Supported Languages'
+---
 # Nix
 
 ## Astal
@@ -74,11 +79,16 @@ Using Astal on Nix will require you to package your project.
 }
 ```
 
+```nix [<i class="devicon-typescript-plain"></i> TypeScript]
+# The usage of AGS (read below) is recommended
+# Usage without AGS is not yet documented
+```
+
 :::
 
 ## AGS
 
-The recommended way to use AGS on NixOS is through the home-manager module.
+The recommended way to use [AGS](../ags/first-widgets#first-widgets) on NixOS is through the home-manager module.
 
 Example content of a `flake.nix` file that contains your `homeConfigurations`.
 
@@ -144,7 +154,7 @@ Example content of `home.nix` file
 
 :::
 
-AGS by default only includes the core `libastal` library.
+AGS by default only includes the core `astal3/astal4` and `astal-io` libraries.
 If you want to include any other [library](../libraries/references) you have to add them to `extraPackages`.
 You can also add binaries which will be added to the gjs runtime.
 
@@ -158,7 +168,11 @@ The AGS flake does not expose the `astal` cli to the home environment, you have
 :::code-group
 
 ```nix [<i class="devicon-nixos-plain"></i> home.nix]
-home.packages = [ inputs.ags.packages.${pkgs.system}.astal ];
+home.packages = [ inputs.ags.packages.${pkgs.system}.default ];
+```
+
+```sh [<i class="devicon-bash-plain"></i> sh]
+astal --help
 ```
 
 :::
diff --git a/docs/guide/getting-started/supported-languages.md b/docs/guide/getting-started/supported-languages.md
index 4cb7f3a..47d5dbd 100644
--- a/docs/guide/getting-started/supported-languages.md
+++ b/docs/guide/getting-started/supported-languages.md
@@ -1,9 +1,15 @@
 # Supported Languages
 
+There are currently two languages that have an additional
+Astal package: Lua and Gjs. Their purpose is to abstract away
+Gtk by implementing a state management and UI declaring solution.
+
 ## JavaScript
 
-The main intended usage of Astal is in TypeScript with [AGS](/guide/ags/first-widgets).
-It supports JSX and has a state management solution similar to web frameworks.
+The main intended usage of Astal is in TypeScript+JSX.
+It is recommended to use [AGS](/guide/ags/first-widgets) to scaffold and run projects in TypeScript.
+However, if you are familiar with JavaScript's tooling
+ecosystem you can also setup an environment yourself.
 Only a minimal knowledge of JavaScript's syntax is needed to get started.
 
 :::info
@@ -17,11 +23,7 @@ Examples:
 
 ## Lua
 
-Similar to how there is a [TypeScript](https://github.com/Aylur/astal/tree/main/core/gjs) lib for GJS, there is also an accompanying library for [Lua](https://github.com/Aylur/astal/tree/main/core/lua).
-<!--TODO: open issue and link performance issue-->
-Unfortunately, I have encountered very heavy [performance issues](https://github.com/aylur/astal) with [lgi](https://github.com/lgi-devs/lgi),
-and so currently I don't recommend using Lua for full desktop shells, but only for static
-components that don't render child nodes dynamically, bars and panels for example.
+Lua is well-supported, but I would still recommend TypeScript, as Lua lacks a type system, which in turn limits editor support.
 
 Examples:
 
@@ -30,10 +32,9 @@ Examples:
 
 ## Python
 
-There was a WIP [library for python](https://github.com/aylur/astal/tree/feat/python), to make it behave similar to the above two
-but I don't plan on finishing it, because I'm not a fan of python.
-If you are interested in picking it up, feel free to open a PR.
-Nonetheless you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it.
+There is a WIP [package for python](https://github.com/aylur/astal/tree/feat/python),
+to bring declaritivity to Python similar to the above two languages.
+However, you can still use python the OOP way [pygobject](https://pygobject.gnome.org/tutorials/gobject/subclassing.html) intended it in the meantime.
 
 Examples:
 
@@ -44,7 +45,7 @@ Examples:
 
 Vala is a language that simply put uses C# syntax and compiles to C.
 It is the language most of Astal is written in. I would still recommend
-using TypeScript or Lua over Vala as they don't need a build step.
+using TypeScript or Lua over Vala as they are simpler to work with.
 
 Examples: