Refactor/Restructure documentation

CONTRIBUTING.md

@@ -1,17 +1,32 @@
-# Ground rules on contributing to Workflow Tiling
-
-Welcome! Thanks for wanting to contribute. If you have any issues reach out to the maintainer.
-
-## Branching Structure
+# Development Guidelines for `Workflow Tiling`
+Welcome! Thanks for wanting to contribute. If you have any issues please reach out to the maintainer.
 
+## Branch Structure
 We follow a structured branching model to keep things organized:
 
 *   **`master`**: This is our stable, release-ready branch. Please do not push directly here.
 *   **`develop`**: This is where new features come together for integration testing. Once the testing phase is complete, `develop` merges into `master` for a new release.
 *   **`feature/*`, `bugfix/*`, `refactor/*`**: Use these short-lived branches for your daily work. When ready, open a Pull Request into `develop`.
 *   **`hotfix/*`** (Exception): If `master` breaks, you can create a hotfix branch to merge directly into `master`.
 
-## Development Guidelines
+## Issues and Feature Requests
+Please report issues and request features under issues.
+
+### AI Friendliness
+This project has a project-level `AGENTS.md` set up. 
+You may have your own requirements in `CLAUDE.md`, `CODEX.md`, `CURSOR.md`, or `GEMINI.md`.
+Please make sure to tell your agent to respect both `AGENTS.md` and your local instruction file.
+
+### Settings UI Design
+We love a clean UI! For `prefs.js`, follow a **"minimal clutter, expand only after needed"** design philosophy.
+Feel free to use `Adw` (libadwaita) components and bind visibility state dynamically to reduce visual noise.
+
+### Logging
+Using debuggable logging (`Logger` in `lib/logger.js`) is highly suggested. Including verbose logs for complex state sequences makes troubleshooting much easier for everyone — especially me. Thank you!
+
+### GNOME APIs & Event-Driven Architecture
+We aim to use the newest solutions and APIs available for GNOME Shell.
+Please rely on GNOME Shell signals (`size-changed`, `window-created`, etc.) or frame-synced deferrals (`GLib.idle_add`, `Meta.LaterType.BEFORE_REDRAW`) instead of arbitrary timeouts (`GLib.timeout_add`).
 
 ### Testing
 We highly value stability! Please make sure to write unit tests for new features—wherever possible—and run existing tests before proposing a change.
@@ -24,20 +39,3 @@ npm test
 We prefer documentation that describes the current state and behavior of the system.
 * Try to keep comments focused without diary entries or historical tracking.
 * If your changes affect how the system works (class names, execution flow, or API), please help us keep `architecture.md`, `layouts.md`, and `README.md` up-to-date!
-
-### Logging
-Using debuggable logging (`Logger` in `lib/logger.js`) is highly suggested. Including verbose logs for complex state sequences makes troubleshooting much easier for everyone—especially me. Thanks!
-
-### Settings UI Design
-We love a clean UI! For `prefs.js`, follow a **"minimal clutter, expand only after needed"** design philosophy.
-Feel free to use `Adw` (libadwaita) components and bind visibility state dynamically to reduce visual noise.
-
-### GNOME APIs & Event-Driven Architecture
-We aim to use the newest solutions and APIs available for GNOME Shell.
-Please rely on GNOME Shell signals (`size-changed`, `window-created`, etc.) or frame-synced deferrals (`GLib.idle_add`, `Meta.LaterType.BEFORE_REDRAW`) instead of arbitrary timeouts (`GLib.timeout_add`).
-
-### AI Friendliness
-This project has a project-level `AGENTS.md` set up. 
-You may have your own requirements in `CLAUDE.md`, `CODEX.md`, `CURSOR.md`, or `GEMINI.md`.
-Please make sure to tell your agent to respect both `AGENTS.md` and your local instruction file.
-

README.md

@@ -1,23 +1,35 @@
 [![Project Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/KonstantinMerkel/workflow-tiling)
 
 # Workflow Tiling
-
 A deterministic customizable auto-tiler extension for GNOME Shell (GNOME 50+).
 
+## Summary
+- [Workflow Tiling](#workflow-tiling)
+  - [Summary](#summary)
+  - [Features](#features)
+  - [Customizations](#customizations)
+    - [Custom Layouts](#custom-layouts)
+  - [Development](#development)
+    - [Contributing](#contributing)
+    - [Running Tests](#running-tests)
+    - [Installation](#installation)
+  - [Recommended Extensions](#recommended-extensions)
+
 ## Features
 - **Deterministic Escalation**: Automatically tiles windows in a customizable geometric sequence.
 - **Multi-Monitor Support**: Each monitor tiles independently.
 - **Workspace Isolation**: Tiling states are unique to each GNOME workspace.
 - **Stability Focused**: Uses WindowWrapper object modeling and compositor-native synchronization (Meta.LaterType) to prevent race conditions and Shell crashes.
 
-## Recommended Extensions
-Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like **P7 Border** 
+## Customizations
+
+Customizations like window gaps and keybinds can be customized under `Gnome Extension Manager` > `Workflow Tiling` > Settings.
+Please be warned that duplicate shortcuts can lead to unexpected window movement.
 
-## Custom Layouts
+### Custom Layouts
 Layout transitions are configured via JSON string, supporting custom window counts and sizes.
 
 Optional `id` (1-indexed) integer properties in the JSON structure define how windows transition between states. It is required for all elements:
-
 ```json
 {
   "1": [
@@ -37,6 +49,9 @@ Optional `id` (1-indexed) integer properties in the JSON structure define how wi
 
 ## Development
 
+### Contributing
+see [CONTRIBUTING.md](CONTRIBUTING.md)
+
 ### Running Tests
 Unit tests are written using **Vitest**.
 ```bash
@@ -49,3 +64,6 @@ To deploy the extension to your local GNOME Shell directory:
 ```bash
 make install
 ```
+
+## Recommended Extensions
+Workflow Tiling does not natively draw an active window border. For visual indication of the focused window, it is highly recommended to use an extension like [P7 Border](https://github.com/prasannavl/p7-borders-shell-extension)