docs(rexx): refine prompt and analysis for Object Rexx address book project

- Update prompt in .grokkit/prompts/rexx.md to emphasize Object Rexx features, extensions, and educational focus.
- Revise analysis.md with improved tech stack descriptions, function references, data flow, and learning path for better clarity and precision.

.grokkit/prompts/rexx.md

@@ -1,11 +1,11 @@
-You are an expert **Object Rexx** educator and codebase archaeologist helping a learning developer or hobbyist deeply understand a modern Object Rexx application that uses Unix and SQLite extensions for the backend and ncurses for the frontend.
+You are an expert **Object Rexx** educator and codebase archaeologist helping a learning developer or hobbyist deeply understand a modern Object Rexx application that combines classic Rexx scripting with Unix, SQLite, and ncurses extensions to build a full-featured terminal address book.
 
 Generate a **single, clean, educational Markdown report** with these **exact sections** (use proper Markdown headings and bullet points only):
 
 # Project Analysis: rexx-address-book
 
 ## Tech Stack & Layout
-- Language (Object Rexx), extensions used (Unix, SQLite, ncurses), configuration approach, and why these were chosen
+- Language (Object Rexx), key extensions (Unix, SQLite, ncurses), configuration approach, and why these were chosen
 - High-level directory structure and purpose of each major directory/file (`app/`, `db/`, `tests/`, `addrbook.rex`, `install.rex`, `default-config.json`)
 
 ## Module & Function Relationships
@@ -16,15 +16,14 @@ Generate a **single, clean, educational Markdown report** with these **exact sec
 ## Function & Method Reference
 Group by source file or logical module. For every major function or method:
 - What it does
-- How it works (key logic, use of Rexx classes/objects, SQLite interaction, ncurses UI handling, string processing)
+- How it works (key logic, use of Object Rexx classes/objects, stems, SQLite interaction, ncurses UI handling)
 - Why it exists (design rationale, separation of concerns, or usability goal)
 
 Pay special attention to:
-- Use of Object Rexx features (classes, methods, stems, etc.)
+- Object Rexx OOP features (classes, methods, `::requires`, stems)
 - SQLite integration for persistent contact storage
-- ncurses-based text user interface
+- ncurses-based text user interface (TUI)
-- Configuration-driven design
+- Configuration-driven design and installation flow
-- Installation and setup flow
 
 ## Object & Data Flow
 - Main data structures (contact records, configuration objects)
@@ -33,8 +32,9 @@ Pay special attention to:
 
 ## Learning Path & Gotchas
 - Recommended order to read and understand the codebase
-- Common pitfalls for newcomers to Object Rexx (especially when mixing classic Rexx, Object Rexx, and external extensions)
+- Common pitfalls for newcomers to Object Rexx (mixing classic Rexx with OOP, extension loading, stems vs objects)
-- Gotchas with ncurses integration, SQLite usage in Rexx, platform differences (Unix extensions)
+- Gotchas with ncurses integration, SQLite usage in Rexx, and platform differences
-- Why certain design decisions were made (separation of UI and data layers, use of JSON config, etc.)
+- Why certain design decisions were made (separation of UI and data layers, use of JSON config, minimal external dependencies)
+
+Be precise, encouraging, and educational. Emphasize how this project demonstrates building a real, full-featured CLI/TUI application in Object Rexx using its powerful extensions. Use short, relevant code snippets only when they clearly illustrate a concept. Do **not** add extra commentary outside the defined sections. Avoid repeating the same idea across sections.
 
-Be precise, encouraging, and educational. Emphasize Object Rexx idioms, the power of its extensions (Unix, SQLite, ncurses), and how this project demonstrates building a real CLI application with a TUI in Rexx. Use short, relevant code snippets only when they clearly illustrate a concept. Do **not** add extra commentary outside the defined sections.

analysis.md

@@ -1,44 +1,48 @@
 # Project Analysis: rexx-address-book
 
 ## Tech Stack & Layout
-- **Language (Object Rexx), extensions used (Unix, SQLite, ncurses), configuration approach, and why these were chosen**: This project is built in Object Rexx, an object-oriented extension of classic Rexx, chosen for its simplicity, powerful string handling, and cross-platform scripting capabilities, making it ideal for a lightweight CLI application like an address book. It leverages Unix extensions for system-level operations (e.g., file I/O, environment variables), SQLite extensions for efficient, embedded database storage without needing a full DBMS, and ncurses for creating a text-based user interface (TUI) that's responsive in terminal environments. Configuration uses a JSON file (default-config.json) parsed via Rexx utilities, allowing flexible, external customization without code changes—chosen for modularity and ease of deployment in varied environments.
+- Object Rexx serves as the core language, blending procedural scripting with OOP for modular, extensible code; key extensions include Unix for system interactions (e.g., file handling, environment vars), SQLite for lightweight persistent storage, and ncurses for building a terminal-based UI (TUI); configuration uses JSON for flexibility, chosen to leverage Rexx's strengths in scripting while adding modern data and UI capabilities without heavy dependencies.
-- **High-level directory structure and purpose of each major directory/file (`app/`, `db/`, `tests/`, `addrbook.rex`, `install.rex`, `default-config.json`)**: The root contains top-level scripts; `app/` houses core application classes and utilities (e.g., appdb.cls for database logic, appui.cls for UI handling, utils.rex for shared functions like string processing); `db/` (if present, or integrated into app/) manages SQLite schema or scripts for data persistence; `tests/` contains unit tests (e.g., test_appdb.rexx for validating database operations); `addrbook.rex` is the main executable script orchestrating the app; `install.rex` handles setup like dependency checks and config initialization; `default-config.json` provides default settings for paths, UI themes, and database connections.
+- High-level directory structure includes `app/` for core application modules and classes (e.g., database and UI logic), `db/` for database-related scripts or schemas (though integrated into `app/` in this setup), `tests/` for unit tests (e.g., database functionality), `addrbook.rex` as the main entry point script, `install.rex` for setup and configuration, and `default-config.json` for default settings like DB paths and UI themes, ensuring easy customization and portability.
 
 ## Module & Function Relationships
-- **How the main script (`addrbook.rex`) and supporting scripts (`install.rex`) relate to each other**: `addrbook.rex` serves as the entry point, requiring classes from `app/` to initialize the UI and database, then entering a main loop for user interactions. `install.rex` is a prerequisite script run once to set up the environment (e.g., creating the SQLite database file and copying default-config.json), ensuring `addrbook.rex` can run smoothly without setup errors—promoting a clean separation between installation and runtime.
+- The main script `addrbook.rex` acts as the orchestrator, loading classes from `app/` and invoking `install.rex` for initial setup; `install.rex` handles environment checks, DB initialization, and config loading to prepare the app for runtime.
-- **Role of the SQLite backend versus the ncurses frontend**: The SQLite backend (via appdb.cls) handles persistent storage of contact data, providing CRUD operations (create, read, update, delete) on records in a lightweight, file-based database. The ncurses frontend (via appui.cls) manages the TUI, rendering menus, forms, and lists interactively in the terminal, abstracting user input/output from data logic for modularity.
+- The SQLite backend (via `app/appdb.cls`) manages data persistence for contacts, while the ncurses frontend (via `app/appui.cls`) handles user interactions like menus and forms, separating concerns for maintainability.
-- **How configuration (`default-config.json`) ties the pieces together**: The JSON config is loaded at startup in `addrbook.rex` (or during install via `install.rex`), populating Object Rexx objects or stems with settings like database path, UI colors, and field labels. This decouples hard-coded values, allowing the backend (SQLite connections) and frontend (ncurses displays) to adapt dynamically, enhancing portability and user customization.
+- Configuration in `default-config.json` ties pieces together by defining paths (e.g., DB file), UI settings (e.g., colors), and defaults, which are parsed in `install.rex` and propagated to classes in `app/` for a unified, configurable experience.
 
 ## Function & Method Reference
-**app/appdb.cls (SQLite Backend Module)**:
+### addrbook.rex (Main Entry Point)
-- **`init` method**: Initializes the SQLite connection using Rexx's SQLite extension; loads config to set database file path and creates tables if needed (e.g., `contacts` with fields like id, name, email). Uses Object Rexx classes to encapsulate the connection object, ensuring thread-safe access; exists for separation of concerns, isolating data persistence from UI.
+- **main()**: Orchestrates app startup by loading configs, initializing DB and UI objects, and entering the main event loop; uses `::requires` to import classes, creates instances like `AppDB` and `AppUI`, and calls UI methods for user interaction; exists to centralize control flow, promoting a clean separation between setup and runtime.
-- **`addContact` method**: Inserts a new contact record into SQLite via prepared statements (e.g., `sqlite_exec("INSERT INTO contacts ...")`); takes a stem or object as input for fields, handles transactions for atomicity. Leverages Object Rexx stems for flexible data passing; designed for reusability and to prevent SQL injection through parameterized queries.
+- **handleExit()**: Cleans up resources like closing DB connections and ncurses sessions on exit; employs Object Rexx's `guard off` for safe object destruction and Unix extensions for any file cleanup; designed for graceful shutdown, ensuring data integrity and resource management.
-- **`getContacts` method**: Queries and returns a list of contacts as an Object Rexx array or directory; uses `sqlite_query` to fetch rows, mapping results to objects. Exists to abstract database reads, supporting efficient searching/sorting for the UI layer.
 
-**app/appui.cls (ncurses Frontend Module)**:
+### install.rex (Setup Script)
-- **`drawMenu` method**: Uses ncurses functions (e.g., `initscr()`, `newwin()`) to render a menu window with options like "Add Contact" or "Search"; processes key inputs via `getch()`. Employs Object Rexx methods for event handling loops; rationale is to provide an intuitive TUI, separating visual rendering from data ops for easier maintenance.
+- **install()**: Checks system dependencies, parses `default-config.json` using Rexx stems for JSON data, sets up SQLite DB schema if needed; leverages Unix extensions for path validation and file creation; exists to make the app portable and user-friendly, handling one-time setup without cluttering the main script.
-- **`editForm` method**: Creates a form window for editing contacts, using ncurses fields and panels; validates input with Rexx string functions (e.g., `verify()`). Integrates with appdb.cls by calling methods like `addContact`; exists to handle user interactions modularly, improving usability in terminal environments.
+- **configLoad()**: Reads and validates JSON config into a Rexx directory object; uses classic Rexx parsing with stems to convert JSON to accessible structures; rationale is to enable dynamic configuration, allowing easy tweaks without code changes.
 
-**app/utils.rex (Utility Functions)**:
+### app/appdb.cls (Database Class)
-- **`parseConfig` function**: Reads and parses default-config.json into a Rexx stem (e.g., `config.dbpath = "addrbook.db"`); uses string processing like `linein()` and JSON decoding logic. Why: Centralizes config handling, enabling configuration-driven design across modules.
+- **init()**: Initializes SQLite connection using extension calls like `sqlite_open`; sets up stems for contact records (e.g., `contacts.name`, `contacts.email`); uses Object Rexx classes for encapsulation, ensuring DB ops are object-oriented; exists to abstract storage, separating data logic from UI.
-- **`validateInput` function**: Checks strings for validity (e.g., email format via Rexx patterns); returns errors as objects. Uses classic Rexx parsing for efficiency; separates validation logic to enforce data integrity without cluttering core classes.
+- **addContact()**: Inserts a new contact via SQLite execute with parameterized queries to prevent injection; maps input stems to SQL, handles transactions; designed for safety and efficiency, demonstrating Rexx's stem usage for flexible data handling.
+- **queryContacts()**: Retrieves contacts with SQL select, populates Rexx arrays or stems; integrates SQLite results into objects; rationale is query optimization and easy data flow to UI, using OOP methods for reusability.
 
-**addrbook.rex (Main Script)**:
+### app/appui.cls (UI Class)
-- **`main` routine**: Requires classes, initializes UI and DB objects, enters a loop calling UI methods based on user choices, which in turn invoke DB operations. Uses Object Rexx's `::requires` for modularity; exists as the orchestrator, demonstrating how extensions integrate into a cohesive app.
+- **init()**: Starts ncurses session with `initscr()` and sets up windows/menus; uses Object Rexx methods to manage UI state objects; exists to encapsulate TUI logic, leveraging ncurses for interactive terminal apps without GUI overhead.
+- **displayMenu()**: Renders main menu using ncurses panels and handles key inputs via `getch()`; employs loops with conditionals for navigation, updating UI objects dynamically; designed for usability, separating input handling from business logic.
+- **editContactForm()**: Creates form fields for contact editing, validates input, and calls DB methods; uses ncurses forms extension and Rexx stems for form data; rationale is intuitive user experience, with error handling built into methods.
 
-**install.rex (Setup Script)**:
+### app/utils.rex (Utility Functions)
-- **`setup` routine**: Checks for extensions, creates DB file via SQLite calls, and generates default-config.json. Uses Unix extensions for file ops (e.g., `SysFileExists()`); designed for one-time setup, ensuring portability and error-free first runs.
+- **parseJson()**: Converts JSON strings to Rexx directories using procedural parsing; classic Rexx string functions like `pos()` and `substr()`; exists as a helper to avoid external libs, supporting config-driven design.
+- **logError()**: Logs errors to file or console using Unix extensions; simple procedural function with condition signals; designed for debugging and robustness, keeping utils lightweight.
 
-**tests/test_appdb.rexx (Testing Module)**:
+### tests/test_appdb.rexx (Test Suite)
-- **`testAddContact` routine**: Creates a temp DB, calls `addContact`, asserts results with Rexx comparisons. Uses Object Rexx for test fixtures; exists to verify backend reliability, promoting test-driven development.
+- **testAddContact()**: Mocks DB insert and asserts results using Rexx's `assert` equivalents; calls class methods and checks stems; exists for TDD, ensuring DB reliability through isolated testing.
+- **testQuery()**: Simulates queries and validates output structures; uses Object Rexx's testing patterns; rationale is to catch issues early, demonstrating separation of tests from production code.
 
 ## Object & Data Flow
-- **Main data structures (contact records, configuration objects)**: Contact records are stored as Object Rexx directories or custom classes (e.g., `.Contact~new` with attributes like `name.`, `email.`), persisted in SQLite tables. Configuration is a stem (e.g., `config.`) loaded from JSON, holding paths and settings as string or numeric values.
+- Main data structures include contact records as Rexx stems (e.g., `contact.1.name = "John"`) for flexible storage, and configuration as directory objects (e.g., `config~dbPath`) for easy access.
-- **Flow of data from user input through the ncurses UI → business logic → SQLite backend (and vice versa for display)**: User input (e.g., key presses) is captured in appui.cls methods, validated via utils.rex, then passed as objects/stems to appdb.cls for SQLite ops (e.g., insert/query). Retrieval flows backward: DB queries return arrays, which UI methods format into ncurses windows for display, ensuring bidirectional data syncing.
+- Data flows from user input via ncurses UI methods (e.g., form submissions) to business logic in `addrbook.rex` (validation), then to SQLite backend for storage/retrieval (e.g., `appdb~addContact(stem)`); reverse flow pulls DB data into stems, formats via utils, and displays in UI windows.
-- **Error handling and safety patterns used in Object Rexx**: Uses `signal on syntax` for trapping errors, with custom handlers returning user-friendly messages via ncurses dialogs. SQLite transactions ensure data integrity; Object Rexx guards (e.g., `guard on`) prevent concurrent issues, emphasizing safe, idiomatic error management in extensions.
+- Error handling uses Object Rexx's `signal on` for conditions like `syntax` or `novalue`, with try-catch patterns in methods; safety includes parameterized SQLite queries and ncurses refresh checks to prevent crashes or data corruption.
 
 ## Learning Path & Gotchas
-- **Recommended order to read and understand the codebase**: Start with `install.rex` to grasp setup flow, then `addrbook.rex` for the high-level orchestration. Dive into `app/utils.rex` for foundational helpers, followed by `app/appdb.cls` to learn SQLite integration, and `app/appui.cls` for ncurses TUI. Finish with `tests/test_appdb.rexx` to see validation in action—this order builds from setup to core logic, mirroring real-world development.
+- Start with `addrbook.rex` for overall flow, then `install.rex` for setup, followed by `app/appdb.cls` and `app/appui.cls` to grasp OOP integration, utils for helpers, and tests for validation; this order builds from high-level to details.
-- **Common pitfalls for newcomers to Object Rexx (especially when mixing classic Rexx, Object Rexx, and external extensions)**: Mixing classic Rexx procedural code with Object Rexx classes can lead to scope issues (e.g., forgetting `self` in methods); extensions like SQLite may require specific interpreter versions—always check `::requires`. Over-relying on stems without classes misses OOP benefits like encapsulation.
+- Common pitfalls for Object Rexx newcomers include confusing classic Rexx procedural code with OOP (e.g., overusing globals instead of methods), improper `::requires` for class loading, and mixing stems (dynamic arrays) with true objects—treat stems as lightweight data holders.
-- **Gotchas with ncurses integration, SQLite usage in Rexx, platform differences (Unix extensions)**: Ncurses can leak resources if windows aren't properly closed (use `endwin()` consistently); SQLite in Rexx needs careful error checking on queries, as extensions don't auto-handle all failures. Unix extensions are platform-specific—test on non-Unix systems for fallbacks; config paths may differ (e.g., absolute vs. relative).
+- Gotchas with ncurses include handling terminal resizes or key mappings across platforms (use `resizeterm()`), SQLite in Rexx requires careful extension loading and error codes, and Unix differences (e.g., paths on Windows vs. Linux) may need conditionals.
-- **Why certain design decisions were made (separation of UI and data layers, use of JSON config, etc.)**: Separating UI (ncurses) and data (SQLite) via classes follows MVC principles, making the app extensible (e.g., swap backends). JSON config enables runtime flexibility without recompiles, showcasing Object Rexx's power for real CLI apps. This demonstrates building robust TUIs with extensions, encouraging modular, testable code for hobbyists.
+- Design decisions like UI-DB separation enhance modularity, JSON config allows extensibility without recompiles, and minimal dependencies showcase Object Rexx's power for self-contained CLI/TUI apps, making it ideal for hobbyists building real tools.