the signals and their derived score are provisional and subject to change.
validate manually before sharing.
83e8462a6b03d4a7d428d5c7365e4ec03f3b63a9419ddc33c9599 months agoCo-authored-by: Copilot <175728472+Copilot@users.noreply.github.com># CONFIG KNOWLEDGE BASE
## OVERVIEW
Reactive, file-backed configuration system built on `Quickshell.Io`. Source of truth for all shell modules. Stores JSON in `~/.config/ambxst/config/`. Gracefully handles missing/malformed files by falling back to hardcoded defaults.
## STRUCTURE
- **Config.qml**: Core singleton (>3100 lines). `FileView` monitors disk; `JsonAdapter` creates bidirectional QML bindings. Each module domain (bar, theme, ai, dock, etc.) has its own `FileView`/`JsonAdapter` pair.
- **defaults/# AGENTS.md: modules/notifications/
## OVERVIEW
Notification popup system built on Quickshell.Services.Notifications. Handles display, grouping, dismissal, and action invocation for notifications.
## STRUCTURE
```
modules/notifications/
├── notification_utils.js # Time formatting, body processing
├── NotificationPopup.qml # Scope container with PanelWindow
├── NotificationListView.qml # ListView model binding
├── NotificationDelegate.qml # Core compone# COMPONENTS KNOWLEDGE BASE
## OVERVIEW
Atomic design library for the Ambxst shell. 26 QML components + 29 GLSL shaders (`.frag`/`.vert`/`.qsb`). Every themed container in the shell ultimately uses `StyledRect`. Shader-driven UI for gradients, wavy animations, and panel blur effects.
## STRUCTURE
### Layout & Containers
| Component | Role |
|-----------|------|
| `StyledRect.qml` | **THE** base container. 300+ usages. `variant` prop selects style from `Styling.qml` |
| `PaneRect.qml` | Simplified pane-spe# AGENTS.md - modules/widgets/overview/
## OVERVIEW
Mission Control-style workspace overview. Two layout modes: grid (default) and scrolling. Shows all workspaces with window previews, supports window dragging between workspaces, and fuzzy search.
## STRUCTURE
| File | Role |
|------|------|
| `OverviewPopup.qml` | PanelWindow container. Handles search input, backdrop, visibility state |
| `OverviewView.qml` | Loader switching between grid/scrolling layouts based on `GlobalStates.compositorLayout` |
| `O# THEME KNOWLEDGE BASE
## OVERVIEW
Dynamic theming layer providing colors, icons, and style utilities as singletons. Also generates config files for external apps (Kitty, GTK, Discord, etc.) from the active color palette.
## STRUCTURE
| File | Type | Role |
|------|------|------|
| `Colors.qml` | Singleton | Watches `~/.cache/ambxst/colors.json`. Provides reactive palette (`primary`, `secondary`, `surface`, `onSurface`, etc.) |
| `Styling.qml` | Singleton | `radius(offset)`, `fontSize(offset)`, `getStyled# SERVICES KNOWLEDGE BASE
## OVERVIEW
Backend singletons bridging Wayland protocols, CLI tools (nmcli, upower, wpctl, etc.), and AI providers to the QML UI layer. 30+ services following a "Reactive Singleton" pattern — internal state derived from async system calls, exposed as QML properties.
## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| **Audio/Volume** | `Audio.qml` | PipeWire/PulseAudio via `wpctl`. Sink/source management |
| **Network/WiFi** | `NetworkService.qml` | `nmc# AGENTS.md - modules/notch/
## OVERVIEW
Dynamic island UI with StackView navigation, themes (default/island), and notification popup system.
## STRUCTURE
| File | Purpose |
|------|---------|
| `Notch.qml` | Core dynamic island: StackView, rounded corners with mask, theme rendering, animations |
| `NotchContent.qml` | Screen-specific wrapper: hover detection, reveal logic, persistent Loaders, visibility bindings |
| `NotchWindow.qml` | PanelWindow wrapper (disabled, commented out) |
| `NotchAnimationBeh# AGENTS.md: modules/lockscreen/
## OVERVIEW
Lock screen UI with PAM authentication via WlSessionLockSurface.
## STRUCTURE
```
modules/lockscreen/
├── LockScreen.qml # Main component (750 lines)
├── ambxst-auth # Helper script (if any)
└── config/pam/ # PAM configuration
└── password.conf # Custom PAM rules for lockscreen
```
Related: `modules/widgets/dashboard/widgets/LockPlayer.qml` (music player on lock screen).
## WHERE TO LOOK
| Symbol | Locatio# PROJECT KNOWLEDGE BASE
**Generated:** 2026-03-01
**Framework:** QtQuick / Quickshell
**Language:** QML / JavaScript
## IMPORTANT: axctl Build Requirement
When changes are made to axctl (in `/home/adriano/Repos/Axenide/axctl/`), manual build and install is required:
1. Build: `cd /home/adriano/Repos/Axenide/axctl && go build -o bin/axctl .`
2. Install: Replace `/usr/local/bin/axctl` with the new binary (requires manual intervention)
The agent cannot test axctl changes directly because the backend runs# BAR MODULE KNOWLEDGE BASE
## OVERVIEW
Primary system panel supporting horizontal (top/bottom) and vertical (left/right) orientations, reactive auto-hiding, and space reservation via Quickshell's `PanelWindow`. Rendered inside `UnifiedShellPanel`.
## STRUCTURE
- **Core Layout**:
- `BarContent.qml` (767 lines): Orchestrates widget groups via `RowLayout`/`ColumnLayout`. Manages auto-hide with `reveal` property + `hideDelayTimer`.
- `BarBg.qml` / `BarBgShadow.qml`: Background aesthetic layers.
- **Widge# AGENTS.md: modules/widgets/launcher/
## OVERVIEW
Multi-tab launcher with unified search. Combines app search, clipboard, emoji, tmux, and notes into single interface with prefix-based tab switching.
## STRUCTURE
```
launcher/
├── LauncherView.qml # 1243 lines. Root component, tab orchestration, unified search
└── qmldir
```
## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| **Unified search logic** | LauncherView.qml lines 84-118 | `detectPrefix()` - maps prefix t# SCRIPTS KNOWLEDGE BASE
## OVERVIEW
Remaining Bash utilities. All Python and most Bash logic has moved into the Go backend (`backend/`): services (`systemmonitor`, `sleep`, `weather`, `clipboard`, `network`, `brightness`, `config`, `keystore`, `linkpreview`, `screenshot`, `recorder`) and CLI subcommands (`colorpicker`, `ocr`, `qr`, `lockwall`, `thumbs`, `dthumbs`, `chatlist`, `writeshader`). The scripts below are thin external-tool wrappers kept for compositor/tooling edge cases.
## WHERE TO LOOK
| Scrip# Desktop Module
## OVERVIEW
Desktop background layer with icon grid, supporting drag-and-drop reordering, thumbnails, and file operations via DesktopService.
## STRUCTURE
- `Desktop.qml` — PanelWindow with icon grid. Uses WlrLayershell Bottom layer. Grid computed from `iconSize` + `spacingVertical`.
- `DesktopIcon.qml` — Individual icon delegate. Handles click/double-click, context menu, thumbnail loading.
## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Icon positioning | # DASHBOARD KNOWLEDGE BASE
## OVERVIEW
Central interactive hub of Ambxst. Tabbed interface with LRU-based lazy-loading for widgets, system controls, media, AI tools, clipboard, notes, and tmux management. Opened via the Notch overlay.
## STRUCTURE
- **Root**: `Dashboard.qml` — Orchestrates LRU logic, tab layout, and open/close animations.
- **Side Tabs**: Vertical navigation bar on the left for switching main views.
- **Sub-tabs** (each a directory):
- `widgets/`: `WidgetsTab` — Main grid: `FullPlaynone