chore: adjusted readme

Author: Cyneric

README.md

@@ -1,133 +1,257 @@
-# aidrelay — AI Developer Relay
+# aidrelay
 
-**Centralized MCP server config and AI coding rules manager for Windows.**
+aidrelay is a Windows desktop app that lets you manage MCP servers, AI rules, skills, and sync workflows across multiple AI coding tools from one place. Instead of editing many client-specific JSON and markdown files, you maintain one source of truth and sync from there.
 
-aidrelay gives you a single place to manage your Model Context Protocol (MCP) server configurations and AI coding rules across every AI development tool on your machine — Cursor, VS Code, Claude Desktop, Windsurf, Zed, JetBrains, and more.
+Supported clients include Cursor, VS Code, Claude Desktop, Windsurf, Zed, JetBrains IDEs, Claude Code, and Codex.
 
----
+![aidrelay dashboard](resources/screenshots/dashboard.png)
 
-## What it does
+## What It Does
 
-- **One config, all tools.** Add an MCP server once and aidrelay syncs it to every AI tool you have installed — no more editing JSON files by hand in five different locations.
-- **AI rules management.** Write and maintain your AI coding rules in Markdown, then sync them to `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, or any other format your tools understand.
-- **Profiles.** Create named configurations (e.g. "Work", "Personal", "Client X") and switch between them with one click — or right from the system tray.
-- **Backup & restore.** Every sync creates a snapshot of the client config before touching it. Roll back to any previous state in one click.
-- **Secrets management.** Environment variable secrets are stored in Windows Credential Manager (via `keytar`), never in plain text.
-- **Registry browser.** Search the Smithery MCP registry and install servers directly.
-- **Git sync.** Push your entire config to a private Git repository for cross-machine portability.
+- Centralizes MCP server and AI rule management for multiple AI clients.
+- Helps you install and maintain skills, MCP registry entries, and local tool setup.
+- Adds safer sync workflows with previews, conflict handling, backups, and restore options.
 
----
+## What Problem It Solves
 
-## Tech stack
+- You keep the same MCP server setup in several tools and configs drift over time.
+- You maintain separate AI rules files for each client format.
+- You need to manage skill files and setup state across machines and projects.
+- Manual edits are easy to break, hard to validate, and hard to roll back.
+- Moving your setup between machines takes too much repeated work.
 
-| Layer | Technology |
-|-------|-----------|
-| Shell | Electron 34+ via electron-vite |
-| UI | React 19, TypeScript (strict), Tailwind CSS 4, shadcn/ui |
-| State | Zustand |
-| Routing | TanStack Router |
-| Tables | TanStack Table |
-| Forms | React Hook Form + Zod |
-| Code editor | Monaco Editor |
-| Markdown | @uiw/react-md-editor |
-| Database | better-sqlite3 (local SQLite) |
-| Secrets | keytar (Windows Credential Manager) |
-| Git | isomorphic-git |
-| i18n | i18next + react-i18next |
-| Packaging | electron-builder (NSIS installer) |
-| Auto-update | electron-updater + GitHub Releases |
+## Who It Is For
+
+- Developers who use more than one AI coding tool.
+- Developers who want one source of truth for MCP servers, rules, and skills.
+- Users who want local-first control with backup and restore options.
+
+## Features
+
+### Dashboard And Client Operations
+
+- Detect installed clients and their config status in one dashboard.
+- Install supported clients, validate configs, and manage per-client sync items.
+- Preview sync changes before writing and confirm only actionable updates.
+- Preview and import config differences found in client files.
+
+### MCP Server Management
+
+- Create, edit, enable, disable, and delete MCP servers from one table.
+- Test server connectivity directly from the server list.
+- Control per-client server toggles with a matrix view.
+- Import servers from existing client configs.
+- Run install and repair flows with the local installer wizard.
+
+### Rules Management
+
+- Create, edit, enable, disable, and delete rules in one place.
+- Filter by category, switch between global and project scopes, and sync to clients.
+- Import rules from project files.
+- Track estimated token usage with a token budget panel.
+
+### Profiles
+
+- Create and manage named profiles for different contexts.
+- Switch active profiles and apply profile changes through an activation flow.
+
+### Skills Management (CRUD + Sync)
+
+- Browse curated skills and install with a preview-first flow.
+- Choose safe install or replace when conflicts are detected.
+- Create your own skills with a step-by-step wizard.
+- Edit skill files, reveal paths, enable or disable, and delete installed skills.
+- Run legacy skill migration and resolve skill sync conflicts.
+
+### Registry Install
+
+- Search and browse MCP servers from Smithery and Official MCP Registry providers.
+- Prepare install options and install directly into your local server registry.
+
+### Sync Center
+
+- Review post-sync setup items in the Needs Setup tab and apply them.
+- Resolve local vs remote conflicts in the Conflicts tab.
+- Review outgoing changes in Push Review before finalizing decisions.
+- Copy a diagnostics report for troubleshooting.
+
+### Git Sync And Cross-Device
+
+- Connect via GitHub OAuth or manual remote configuration.
+- Test remote connectivity, then pull, push, or disconnect from settings.
+- Use sync conflict and push review workflows to keep machines aligned.
+
+### Safety And Traceability
+
+- Create backups automatically before sync writes.
+- Filter and inspect backup history across clients.
+- Restore older config snapshots when needed.
+- Review a filterable activity log of sync and management actions.
+
+### Portability
+
+- Export selected servers and rules as stack bundles.
+- Import stack bundles to bootstrap or share setups.
+
+### Security And Local-First
+
+- Store secrets in Windows Credential Manager via `keytar`.
+- Keep local state in SQLite on your machine.
+- Avoid storing sensitive tokens in plaintext project files.
+
+## Screenshots
+
+### Dashboard Overview
+
+![Dashboard overview](resources/screenshots/dashboard.png)
+
+### Clients Management
+
+![Clients management](resources/screenshots/clients.png)
+
+### Servers Management
 
----
+![Servers management](resources/screenshots/servers.png)
 
-## Getting started (development)
+### Rules Editor (Markdown + Preview)
+
+![Rules editor](resources/screenshots/rules.png)
+
+### Skills Discovery And Install
+
+![Skills discovery and install](resources/screenshots/skills-dicover.png)
+
+### Skills Installed CRUD
+
+![Skills installed CRUD](resources/screenshots/skills-installed.png)
+
+### Skills Edit Flow
+
+![Skills edit flow](resources/screenshots/skills-edit.png)
+
+### Registry Install (Smithery)
+
+![Registry install Smithery](resources/screenshots/registry.png)
+
+### Sync Center Conflicts
+
+@todo Capture Sync Center with Needs Setup and Conflicts counts visible and a conflict resolution card open.
+
+### Profiles And Activation Flow
+
+![Profiles and activation](resources/screenshots/profiles.png)
+
+### History And Restore
+
+![History and restore](resources/screenshots/history.png)
+
+### Activity Log
+
+![Activity log](resources/screenshots/activity-log.png)
+
+### Stacks Import And Export
+
+![Stacks import and export](resources/screenshots/stacks.png)
+
+### Settings + Git Sync
+
+@todo Capture settings with Git Sync section expanded, including remote URL, test remote, pull, push, and disconnect actions.
+
+## Development
 
 ### Prerequisites
 
-- Node.js ≥ 20
-- pnpm ≥ 9
-- Windows 10/11 (primary target; macOS/Linux builds planned)
+- Node.js >= 20
+- pnpm >= 9
+- Windows 10/11 (primary target)
 
 ### Setup
 
 ```bash
-# Clone the repository
+# Clone repository
 git clone https://github.com/christianblank91/aidrelay.git
 cd aidrelay
 
-# Install dependencies (rebuilds native modules automatically)
+# Install dependencies
 pnpm install
 
-# Start in development mode
+# Start development app
 pnpm dev
 ```
 
-The app opens an Electron window with hot-reload. The Chrome DevTools MCP is enabled in dev mode so you can connect to the renderer via `chrome://inspect` on port 9222.
-
 ### Scripts
 
 | Command | Description |
-|---------|-------------|
+| ------- | ----------- |
 | `pnpm dev` | Start Electron in development mode with HMR |
-| `pnpm build` | Compile all processes with electron-vite |
-| `pnpm dist:win` | Build + package a Windows NSIS installer |
-| `pnpm typecheck` | Run TypeScript across all three tsconfigs |
-| `pnpm lint` | ESLint across all source files |
+| `pnpm build` | Build main, preload, and renderer bundles |
+| `pnpm dist:win` | Build and package a Windows installer |
+| `pnpm typecheck` | Run TypeScript checks across all tsconfig targets |
+| `pnpm lint` | Run ESLint across source files |
 | `pnpm test` | Run the full Vitest test suite |
-| `pnpm test:watch` | Vitest in watch mode |
-
----
+| `pnpm test:watch` | Run Vitest in watch mode |
 
-## Project structure
+### Project Structure
 
-```
+```text
 src/
   main/           # Electron main process (Node.js)
-    clients/      # ClientAdapter implementations per AI tool
-    db/           # SQLite repositories + migrations
-    git-sync/     # isomorphic-git wrapper
-    ipc/          # IPC handler registrations
-    registry/     # Smithery API client
-    rules/        # Rule sync, format conversion, token estimator
-    secrets/      # keytar wrapper for Windows Credential Manager
-    sync/         # Safety-first sync service + backup + file watcher
-    testing/      # MCP server connection tester
-    tray/         # System tray icon + profile quick-switch
-    updater/      # electron-updater wrapper
-  preload/        # contextBridge IPC bridge (typed window.api)
+    clients/      # Client adapters per AI tool
+    db/           # SQLite repositories and migrations
+    git-sync/     # isomorphic-git integration
+    ipc/          # IPC handlers
+    registry/     # Registry API clients
+    rules/        # Rule sync and format conversion
+    secrets/      # Secret storage wrapper
+    sync/         # Sync orchestration, backup, file watching
+    testing/      # MCP server connection testing
+    tray/         # System tray integration
+    updater/      # App update integration
+  preload/        # Typed contextBridge API
   renderer/       # React UI
-    components/   # Reusable components, organized by domain
-    i18n/         # English + German translations
-    lib/          # Renderer utility hooks
-    pages/        # One file per route
+    components/   # UI components by domain
+    i18n/         # Translation files
+    pages/        # Route pages
     stores/       # Zustand stores
-  shared/         # Types + IPC channel definitions shared by all processes
+  shared/         # Shared types and IPC channel contracts
 ```
 
----
+### Configuration
 
-## Configuration
+Copy `.env.example` to `.env` and provide OAuth values:
 
-### Environment variables
-
-Copy `.env.example` to `.env` and fill in the values:
-
-```
+```bash
 VITE_GITHUB_CLIENT_ID=your-github-oauth-client-id
 VITE_GITHUB_CLIENT_SECRET=your-github-oauth-client-secret
 ```
 
-If `VITE_GITHUB_CLIENT_ID` or `VITE_GITHUB_CLIENT_SECRET` are missing, the Settings Git Sync flow will show an actionable in-app error and GitHub OAuth connect will not start.
+If these are missing, GitHub OAuth connect in Settings will not start.
 
-Secrets (API tokens, local credentials) are never stored in `.env` — they go through `electron.safeStorage` or the Windows Credential Manager.
+## Tech Stack
 
----
+| Layer | Technology |
+| ----- | ---------- |
+| Shell | Electron 34+ via electron-vite |
+| UI | React 19, TypeScript, Tailwind CSS 4, shadcn/ui |
+| State | Zustand |
+| Routing | TanStack Router |
+| Tables | TanStack Table |
+| Forms | React Hook Form + Zod |
+| Code editor | Monaco Editor |
+| Markdown | @uiw/react-md-editor |
+| Database | better-sqlite3 (local SQLite) |
+| Secrets | keytar (Windows Credential Manager) |
+| Git | isomorphic-git |
+| i18n | i18next + react-i18next |
+| Packaging | electron-builder (NSIS installer) |
+| Auto-update | electron-updater + GitHub Releases |
 
 ## License
 
-MIT License — © 2026 Christian Blank.
+MIT License - Copyright (c) 2026 Christian Blank.
 
 The following companion packages are MIT-licensed and maintained in separate repositories:
 
-- [`@aidrelay/adapter-spec`](https://github.com/christianblank91/aidrelay-adapter-spec) — ClientAdapter interface + format spec
-- [`@aidrelay/rules-format`](https://github.com/christianblank91/aidrelay-rules-format) — AI rules format specification
-- [`@aidrelay/stacks`](https://github.com/christianblank91/aidrelay-stacks) — Community rule templates and MCP stacks
+- [`@aidrelay/adapter-spec`](https://github.com/christianblank91/aidrelay-adapter-spec) - ClientAdapter interface + format spec
+- [`@aidrelay/rules-format`](https://github.com/christianblank91/aidrelay-rules-format) - AI rules format specification
+- [`@aidrelay/stacks`](https://github.com/christianblank91/aidrelay-stacks) - Community rule templates and MCP stacks