================================================================================ csweb-gui / napp-it -- AI-assisted Development with Claude howto.ai/readme.txt ================================================================================ This folder contains documentation for AI-assisted development of csweb-gui/napp-it. Upload the ZIP to Claude together with this folder for best results. guideline.txt -- Development process rules, conventions, session rules behaviours.txt -- Frontend/backend interaction, protocol, all gotchas paths.txt -- Project folder structure and path conventions Always tell Claude at the start of a session: "Please read and follow csweb-gui/howto.ai/guideline.txt" ================================================================================ ENGLISH -- How to use Claude AI to maintain or extend napp-it / csweb-gui ================================================================================ WORKFLOW -------- 1. Create a ZIP of your csweb-gui installation: Windows: right-click csweb-gui folder -> Send to -> Zip Unix: cd /var && zip -r ~/csweb-gui_backup.zip csweb-gui/ 2. Upload the ZIP to Claude at claude.ai 3. Tell Claude: "Please read and follow csweb-gui/howto.ai/guideline.txt [describe your change request here]" 4. Download the ZIP Claude creates and replace the changed files. You only need to replace files that changed -- Claude lists them in the changelog and marks them M (modified) / A (added) / D (deleted). 5. Restart the csweb-gui frontend + backend to pick up changes: Windows: "C:\xampp\csweb-gui\startup\backend+web-gui\windows\__start_zfs-gui_as_admin_debug.bat" (debug mode) Free-BSD sh /var/csweb-gui/startup/backend+web-gui/freebsd/apache_freebsd.sh Linux: frontend + backend v OmniOS se+cs: restart via /etc/init.d/napp-it restart OSX: sh /var/csweb-gui/startup/backend+web-gui/osx/apache_osx.sh Restart Backend only (remote managed server) Windows: "C:\xampp\csweb-gui\startup\backend_only\windows\_start_cs_server_only_as_admin.bat" Non Windows: perl /var/csweb-gui/startup/backend_only/non_windows/_restart_server_foreground.pl (debug mode) WHAT CLAUDE CAN DO ------------------ - Fix bugs in menu actions, libraries, or the backend - Add new features to existing menus - Create new menus (see PRIVATE MENUS below) - Optimize SQL queries, Perl code, PowerShell snippets - Document code, update changelogs and version strings - Review code for security issues - Port functionality between platforms (Windows/OmniOS/Linux) FOLDER STRUCTURE (what to replace after a Claude session) ---------------------------------------------------------- csweb-gui/data/ Core application code (menus, libs, backend) csweb-gui/data/menues/ Menu definitions and action scripts csweb-gui/data/menues/_lib/ Shared libraries (s3lib, zfslib, jobslib, ...) csweb-gui/data/wwwroot/ Frontend CGI (admin.pl, admin-wlib.pl, ...) csweb-gui/data/cs_server/ Backend socket server (server.pl, auto.pl, ...) csweb-gui/startup/ Startup script templates (patched by setup wizard) csweb-gui/howto.ai/ This folder -- AI documentation DO NOT REPLACE these folders (contain your local config and data): csweb-gui/cfg/ Configuration (server.auth, S3 config, ...) csweb-gui/_log/ Logs, job definitions, session files csweb-gui/tmp/ Cache and temporary files PRIVATE MENUS (_my folder) -------------------------- You can add your own menus and overrides without touching the main csweb-gui code. This survives updates since only csweb-gui/data/ is replaced. csweb-gui/_my/ menus/ Your private menus (same structure as data/menues/) _lib/ Your private library overrides interface.pl Override the default UI interface Example: add a custom "My Backup" menu 1. Copy an existing menu folder as template 2. Place it in csweb-gui/_my/menus/XX_My_Backup/ 3. Edit action.pl to add your functionality 4. Tell Claude: "Add a menu in _my/menus that does X" TIPS FOR GOOD RESULTS --------------------- - Upload the actual current ZIP (not an old backup) -- Claude needs the latest code - Be specific: "In data/menues/07_Filesystems/action.pl, the ZFS snapshot list shows an error when the filesystem has no snapshots. Fix it." - Mention your platform: "Windows only", "OmniOS and Linux", "all platforms" - Claude maintains changelogs, version strings, and documentation automatically - Review the changelog in the ZIP to see exactly what changed - For larger projects, use a local Git + Claude Code + Chrome with Claude Extension ================================================================================ DEUTSCH -- Claude AI fuer napp-it / csweb-gui nutzen ================================================================================ ARBEITSABLAUF ------------- 1. ZIP der csweb-gui Installation erstellen: Windows: Rechtsklick auf csweb-gui Ordner -> Senden an -> Zip Unix: cd /var && zip -r ~/csweb-gui_backup.zip csweb-gui/ 2. ZIP bei claude.ai hochladen 3. Claude anweisen: "Bitte lese und befolge csweb-gui/howto.ai/guideline.txt [Aenderungswunsch beschreiben]" 4. ZIP herunterladen und geaenderte Dateien ersetzen. Nur geaenderte Dateien muessen ersetzt werden -- Claude listet sie im Changelog und kennzeichnet sie mit M (geaendert) / A (neu) / D (geloescht). 5. csweb-gui Backend neu starten: Windows: "C:\xampp\csweb-gui\startup\backend+web-gui\windows\__start_zfs-gui_as_admin_debug.bat" (debug mode) Free-BSD sh /var/csweb-gui/startup/backend+web-gui/freebsd/apache_freebsd.sh Linux: frontend + backend v OmniOS se+cs: restart via /etc/init.d/napp-it restart OSX: sh /var/csweb-gui/startup/backend+web-gui/osx/apache_osx.sh Restart Backend only (remote managed server) Windows: "C:\xampp\csweb-gui\startup\backend_only\windows\_start_cs_server_only_as_admin.bat" Non Windows: perl /var/csweb-gui/startup/backend_only/non_windows/_restart_server_foreground.pl (debug mode) WAS CLAUDE KANN --------------- - Bugs in Menue-Aktionen, Bibliotheken oder Backend beheben - Neue Funktionen in bestehende Menues einbauen - Neue Menues erstellen (siehe PRIVATE MENUES) - Code optimieren (Perl, PowerShell) - Code dokumentieren, Changelogs und Versionsnummern aktualisieren - Code auf Sicherheitsprobleme pruefen - Funktionen zwischen Plattformen portieren (Windows/OmniOS/Linux) ORDNERSTRUKTUR (was nach einer Claude-Session zu ersetzen ist) -------------------------------------------------------------- csweb-gui/data/ Hauptcode (Menues, Bibliotheken, Backend) csweb-gui/data/menues/ Menue-Definitionen und Aktionsskripte csweb-gui/data/menues/_lib/ Gemeinsame Bibliotheken csweb-gui/data/wwwroot/ Frontend CGI csweb-gui/data/cs_server/ Backend-Socketserver csweb-gui/startup/ Startskript-Vorlagen csweb-gui/howto.ai/ Dieser Ordner -- KI-Dokumentation NICHT ERSETZEN (enthalten lokale Konfiguration und Daten): csweb-gui/cfg/ Konfiguration (server.auth, S3-Config, ...) csweb-gui/_log/ Logs, Job-Definitionen, Session-Dateien csweb-gui/tmp/ Cache und temporaere Dateien PRIVATE MENUES (_my Ordner) -------------------------- Eigene Menues und Erweiterungen koennen ohne Aenderungen am Hauptcode in csweb-gui/_my/ abgelegt werden. Sie ueberleben Updates/Downgrades, da nur csweb-gui/data/ ersetzt wird. csweb-gui/_my/ menus/ Eigene Menues (gleiche Struktur wie data/menues/) _lib/ Eigene Bibliotheks-Overrides interface.pl Eigenes UI-Interface Beispiel: eigenes "Mein Backup" Menue hinzufuegen 1. Vorhandenes Menue als Vorlage kopieren 2. Nach csweb-gui/_my/menus/XX_Mein_Backup/ legen 3. action.pl anpassen 4. Claude: "Erstelle ein Menue in _my/menues das X macht" TIPPS FUER GUTE ERGEBNISSE -------------------------- - Immer die aktuelle ZIP hochladen (keine alte Sicherung) -- Claude braucht den neuesten Stand - Praezise beschreiben: "In data/menues/07_Filesystems/action.pl erscheint ein Fehler wenn das Dateisystem keine Snapshots hat. Bitte beheben." - Plattform angeben: "Nur Windows", "OmniOS und Linux", "alle Plattformen" - Claude pflegt Changelogs, Versionsnummern und Dokumentation automatisch - Changelog im ZIP pruefen -- zeigt genau was geaendert wurde - For groessere Projekte empfiehlt sich lokales Git + Claude Code + Chrome mit Claude Extension ================================================================================