docs: reset AGENTS.md to minimal header

Author: fbosch

.config/ags/AGENTS.md

@@ -0,0 +1,38 @@
+# Architecture and Components
+
+AGS runs in bundled mode for performance. All components in `lib/` are imported by `config-bundled.tsx` and run in a single GTK process.
+
+Components (in `lib/`):
+
+- `lib/confirm-dialog.tsx` - Confirmation dialog for high-impact operations
+- `lib/keyboard-switcher.tsx` - Keyboard layout switcher overlay
+- `lib/volume-indicator.tsx` - Volume change indicator with automatic monitoring
+- `lib/start-menu.tsx` - System start menu with update badges
+- `lib/window-switcher.tsx` - Alt+Tab window switcher with previews
+
+Entry points:
+
+- `config-bundled.tsx` - Main bundled configuration (imports all components)
+- `start-daemons.sh` - Boot script to start AGS in bundled mode
+
+Bundled mode details:
+
+- Each component window has its own namespace
+- CSS is applied during module loading
+- Components export to `globalThis` for communication
+- Single GTK process hosts all windows
+
+File structure:
+
+```
+.config/ags/
+├── lib/                        # Component library (canonical source)
+│   ├── confirm-dialog.tsx
+│   ├── keyboard-switcher.tsx
+│   ├── volume-indicator.tsx
+│   ├── start-menu.tsx
+│   └── window-switcher.tsx
+├── config-bundled.tsx          # Main entry point (imports from lib/)
+├── config.tsx                  # Stub (bundled mode required)
+└── start-daemons.sh            # Boot script (runs config-bundled.tsx)
+```

.config/ags/docs/agents/architecture.md

@@ -0,0 +1,11 @@
+# Best Practices
+
+1. Prefer JSX over programmatic widget creation.
+2. Use the `setup` callback to capture widget references when you need imperative access.
+3. Set `namespace` on windows for Hyprland layer rules.
+4. Use enums not strings: `Astal.Layer.OVERLAY` not "overlay".
+5. Avoid invalid GTK CSS properties like `max-width` (use `min-width` or GTK properties).
+6. Kill `gjs` to reload CSS changes: `pkill gjs`.
+7. Use GTK Inspector (`ags inspect`) to debug styling.
+8. Use `keymode={Astal.Keymode.EXCLUSIVE}` for dialogs that need focus.
+9. Avoid `ignore_alpha` for solid backgrounds.

.config/ags/docs/agents/best-practices.md

@@ -0,0 +1,51 @@
+# Commands and Setup
+
+## Start bundled AGS
+
+```bash
+./start-daemons.sh
+```
+
+Manual start:
+
+```bash
+ags run ~/.config/ags/config-bundled.tsx
+```
+
+## IPC communication
+
+```bash
+ags msg ags-bundled '{"window":"start-menu","action":"toggle"}'
+ags msg ags-bundled '{"window":"window-switcher","action":"next"}'
+```
+
+## TypeScript type definitions
+
+Type definitions for GObject Introspection libraries are auto-generated in `.config/ags/@girs/` (git-ignored).
+
+Generate types (run after installing AGS or updating GTK libraries):
+
+```bash
+cd ~/.config/ags
+ags types
+```
+
+Regenerate when:
+
+- Fresh system setup
+- After updating AGS or system GTK libraries
+- TypeScript shows "Cannot find module" errors for GI imports
+
+## AGS command reference
+
+```bash
+ags run <file.tsx>
+ags list
+ags request -i <instance-name> '<json-payload>'
+ags quit <instance-name>
+ags toggle <window-name>
+ags types
+ags bundle <file.tsx>
+ags inspect
+~/.config/ags/start-daemons.sh
+```

.config/ags/docs/agents/commands-setup.md

@@ -0,0 +1,99 @@
+# Daemon Lifecycle
+
+## Overview
+
+AGS runs as a single bundled process started at boot. All components are loaded into one process with shared resources for instant UI display and efficient usage.
+
+## Boot process
+
+1. Hyprland starts and runs `~/.config/ags/start-daemons.sh`
+2. Script waits for Hyprland to be ready
+3. Launches `ags run config-bundled.tsx`
+4. Components initialize in a single process
+5. Windows are pre-created (hidden) for instant display
+
+## Startup script (`start-daemons.sh`)
+
+Purpose: manage the bundled AGS process lifecycle.
+
+Features:
+
+- Waits for Hyprland to be ready before starting
+- Checks if bundled process is already running
+- Provides colored console output and logging
+- Logs to `/tmp/ags-daemons.log` for debugging
+
+Usage:
+
+```bash
+exec-once = uwsm app -- ~/.config/ags/start-daemons.sh
+~/.config/ags/start-daemons.sh
+cat /tmp/ags-daemons.log
+ags list
+```
+
+Configuration (top of `start-daemons.sh`):
+
+```bash
+WAIT_FOR_HYPRLAND=true
+HYPRLAND_TIMEOUT=4
+```
+
+## Communication pattern
+
+Components communicate via the `globalThis` namespace.
+
+Component side (TypeScript in `lib/` files):
+
+```tsx
+globalThis.myComponent = {
+  show: () => myWindow.show(),
+  hide: () => myWindow.hide(),
+  toggle: () => myWindow.visible ? myWindow.hide() : myWindow.show(),
+};
+
+const myWindow = (
+  <window name="my-window" namespace="ags-myapp" visible={false}>
+    {/* content */}
+  </window>
+);
+```
+
+Main config (`config-bundled.tsx`):
+
+```tsx
+import "gi://Astal?version=4.0";
+import app from "ags/gtk4/app";
+
+import "./lib/confirm-dialog.tsx";
+import "./lib/keyboard-switcher.tsx";
+import "./lib/volume-indicator.tsx";
+import "./lib/start-menu.tsx";
+import "./lib/window-switcher.tsx";
+
+app.start({
+  instanceName: "ags-bundled",
+  requestHandler(argv: string[], res: (response: string) => void) {
+    try {
+      const data = JSON.parse(argv.join(" "));
+      const component = globalThis[data.window];
+
+      if (component && typeof component[data.action] === "function") {
+        component[data.action]();
+        res("success");
+      } else {
+        res("unknown window or action");
+      }
+    } catch (e) {
+      res(`error: ${e}`);
+    }
+  },
+});
+```
+
+Client side (shell):
+
+```bash
+ags request -i ags-bundled '{"window":"start-menu","action":"toggle"}'
+bind = $mainMod, X, exec, ags request -i ags-bundled '{"window":"start-menu","action":"toggle"}'
+```

.config/ags/docs/agents/daemon.md

@@ -0,0 +1,61 @@
+# GJS/GLib Integration
+
+## Spawning commands
+
+```tsx
+const GLib = imports.gi.GLib;
+
+GLib.spawn_command_line_async("command arg1 arg2");
+
+let [ok, output] = GLib.spawn_command_line_sync("command");
+const decoder = new TextDecoder();
+let result = JSON.parse(decoder.decode(output));
+```
+
+## Keyboard events
+
+```tsx
+const Gtk = imports.gi.Gtk;
+const Gdk = imports.gi.Gdk;
+
+<Gtk.EventControllerKey
+  onKeyPressed={(_, keyval) => {
+    if (keyval === Gdk.KEY_Escape) {
+      app.quit();
+      return true;
+    }
+    return false;
+  }}
+/>
+```
+
+Common key constants:
+
+- `Gdk.KEY_Escape`
+- `Gdk.KEY_Return`
+- `Gdk.KEY_Tab`
+- `Gdk.KEY_space`
+
+## Timeouts
+
+```tsx
+const timeout = GLib.timeout_add(GLib.PRIORITY_DEFAULT, 1000, () => {
+  return GLib.SOURCE_REMOVE;
+});
+
+GLib.source_remove(timeout);
+```
+
+## File monitoring
+
+```tsx
+const Gio = imports.gi.Gio;
+
+const file = Gio.File.new_for_path("/path/to/file");
+const monitor = file.monitor(Gio.FileMonitorFlags.NONE, null);
+monitor.connect("changed", (monitor, file, other_file, event_type) => {
+  if (event_type === Gio.FileMonitorEvent.CHANGED) {
+    // handle change
+  }
+});
+```

.config/ags/docs/agents/gjs-glib.md

@@ -0,0 +1,22 @@
+# Hyprland Integration
+
+## Layer rules
+
+AGS windows need a `namespace` prop for Hyprland layer rules:
+
+```tsx
+<window
+  name="my-window"
+  namespace="ags-myapp" // Used in Hyprland layerrules
+/>
+```
+
+In `hyprland.conf`:
+
+```
+layerrule = match:namespace ags-myapp, blur on
+layerrule = match:namespace ags-myapp, no_anim on
+# Don't add ignore_alpha if you want solid backgrounds.
+```
+
+Hyprland `ignore_alpha` forces transparency. Only add it if you want the layer to be transparent.

.config/ags/docs/agents/hyprland-integration.md

@@ -0,0 +1,5 @@
+# Resources
+
+- Official Docs: https://aylur.github.io/astal/guide/introduction
+- GTK4 CSS: https://docs.gtk.org/gtk4/css-properties.html
+- AGS GitHub: https://github.com/aylur/ags