Improve documentation clarity and fix technical inaccuracies

API-Reference.md

@@ -257,11 +257,10 @@ const timeout = roster.getVariable('timeout') || '30';
 console.log('Using timeout:', timeout);
 ```
 
-**Important Notes:**
+**Notes:**
 - Returns `undefined` if variable doesn't exist
-- Gets value from currently selected environment
+- Gets value from selected environment
-- Can access both regular and [[Sensitive-Variables|sensitive variables]]
+- Sensitive variables are automatically decrypted
-- Sensitive variable values are automatically decrypted from keyring
 
 #### `roster.setVariable(name, value)`
 
@@ -287,12 +286,12 @@ roster.setVariable('auth_token', token);
 roster.setVariable('session_id', generateSessionId());
 ```
 
-**Important Notes:**
+**Notes:**
 - Creates variable if it doesn't exist
-- Updates value in currently selected environment
+- Updates value in selected environment
 - Variable name must be alphanumeric + underscore
-- If variable is marked as sensitive, value goes to keyring automatically
+- Sensitive variables automatically routed to keyring
-- Value is converted to string
+- Value converted to string
 
 #### `roster.setVariables(object)`
 
@@ -323,11 +322,9 @@ roster.setVariables({
 console.log('Saved authentication tokens');
 ```
 
-**Important Notes:**
+**Notes:**
-- All variables updated in single operation
 - More efficient than multiple `setVariable()` calls
 - Same validation rules as `setVariable()`
-- Sensitive variables automatically routed to keyring
 
 ### Properties
 
@@ -554,65 +551,21 @@ if (response.statusCode === 200) {
 
 ## Limitations
 
-### No Asynchronous Operations
+Scripts run in a sandboxed, synchronous environment:
-
+- No async operations (setTimeout, Promises, async/await)
-- No `setTimeout` / `setInterval`
+- No external libraries or npm packages
-- No `Promise` / `async` / `await`
+- No file system or shell access
-- No `fetch()` / `XMLHttpRequest`
+- No network requests (use Roster's request system)
-- Scripts execute synchronously
-
-### No External Libraries
-
-- Cannot import npm packages
-- Cannot `require()` external modules
 - Only built-in JavaScript objects available
 
-### No File System Access
-
-- Cannot read/write files
-- Cannot execute shell commands
-- Cannot access environment variables (use Roster variables instead)
-
-### No Network Access
-
-- Cannot make additional HTTP requests
-- Use Roster's request system instead
-
 ## Type Reference
 
-### Variable Name Pattern
+**Variable names** must match `/^\w+$/` (alphanumeric + underscore only).
-
-Variable names must match: `/^\w+$/`
-
-Valid:
-- `api_key`
-- `user_id`
-- `access_token`
-- `BASE_URL`
-- `token123`
-
-Invalid:
-- `api-key` (hyphen not allowed)
-- `api.key` (dot not allowed)
-- `api key` (space not allowed)
-- `@token` (special character)
-
-### Type Conversions
-
-Variables are always stored as strings:
 
+**Variables are always strings**. Convert numbers and booleans when setting/getting:
 ```javascript
-// Numbers must be converted
 roster.setVariable('count', data.count.toString());
-
-// Read as number
 const count = parseInt(roster.getVariable('count'), 10);
-
-// Booleans must be converted
-roster.setVariable('is_active', data.active.toString());
-
-// Read as boolean
-const isActive = roster.getVariable('is_active') === 'true';
 ```
 
 ## Next Steps

FAQ.md

@@ -33,9 +33,7 @@ Support for Flathub is planned for future releases.
 
 ### What dependencies does Roster need?
 
-Runtime: GTK 4, libadwaita 1, Python 3, libsoup3, libsecret, GJS
+GTK 4, libadwaita 1, Python 3, libsoup3, libsecret, and GJS. See [[Installation]] for details.
-
-See [[Installation]] for complete dependency list.
 
 ## Variables and Environments
 
@@ -76,10 +74,7 @@ Regular variables are stored in plain text. Always mark secrets as sensitive!
 
 ### Where are my secrets stored?
 
-Sensitive variables are stored in GNOME Keyring at:
+Sensitive variables are encrypted in GNOME Keyring (`~/.local/share/keyrings/`) using your login password. Same security as browser passwords and WiFi credentials.
-- Native: `~/.local/share/keyrings/`
-- Encrypted with your login password
-- Same security as browser passwords, WiFi credentials
 
 ### Can I view my keyring secrets?
 
@@ -181,10 +176,9 @@ flatpak info --show-permissions cz.bugsy.roster
 ### Scripts not executing
 
 **Check:**
-1. Request is saved (scripts only work on saved requests)
+1. Script has no syntax errors
-2. Script has no syntax errors
+2. Check script output panels for errors
-3. Check script output tabs for errors
+3. GJS (gjs package) is installed
-4. GJS (gjs package) is installed
 
 ### Request failing with SSL errors
 
@@ -235,23 +229,13 @@ Yes! Open an issue with the "enhancement" label.
 
 ## Comparison
 
-### How is Roster different from Postman?
+### How is Roster different from Postman/Insomnia?
 
-- **Roster**: Native GNOME app, lightweight, open-source, Linux-only
+Roster is a lightweight, native GNOME application focused on simplicity. Unlike Postman/Insomnia (Electron-based with cloud features), Roster is Linux-only with no cloud dependencies.
-- **Postman**: Cross-platform, Electron-based, cloud sync, team features
-
-Roster focuses on being a simple, fast, native GNOME experience.
-
-### How is Roster different from Insomnia?
-
-Similar to Postman comparison. Roster is native GNOME with no cloud dependencies.
 
 ### How is Roster different from HTTPie?
 
-- **Roster**: GUI application with project management
+Roster provides a GUI with project management, while HTTPie is a command-line tool.
-- **HTTPie**: Command-line tool
-
-Roster provides a visual interface while HTTPie is CLI-focused.
 
 ## Still Have Questions?
 

Getting-Started.md

@@ -10,23 +10,9 @@ After [[Installation]], launch Roster from:
 
 ## Your First Request
 
-### Step 1: Create a Project
+### Step 1: Configure the Request
 
-Projects help organize related requests (e.g., "GitHub API", "My App API").
+Roster starts with a new request tab.
-
-1. Click the **hamburger menu** (three lines) in the top-left
-2. Select **"New Project"**
-3. Enter a name: `My First Project`
-4. Click **"Create"**
-
-### Step 2: Create a Request
-
-1. Click the **"+"** button in the header bar
-2. Or: **Ctrl+T** keyboard shortcut
-
-A new request tab appears with default values.
-
-### Step 3: Configure the Request
 
 **Set the URL:**
 ```
@@ -34,30 +20,29 @@ https://api.github.com/users/octocat
 ```
 
 **Set the Method:**
-- Use the dropdown menu
+- Use the dropdown menu (default is `GET`)
-- Default is `GET` (perfect for this example)
 
 **Add Headers (Optional):**
 1. Click the **"Headers"** tab
 2. Add a header:
    - Key: `User-Agent`
-   - Value: `Roster/0.5.0`
+   - Value: `Roster/0.6.0`
 
-### Step 4: Send the Request
+### Step 2: Send the Request
 
 Click the **"Send"** button (or press **Ctrl+Return**)
 
-### Step 5: View the Response
+### Step 3: View the Response
 
 The response appears in the right panel:
 
 **Status Line:**
 ```
-200 OK (123 ms, 1.2 KB)
+200 OK 123 ms 1.2 KB
 ```
 
 **Response Headers:**
-Click the **"Headers"** dropdown to view all response headers.
+Click the **"Headers"** tab to view all response headers.
 
 **Response Body:**
 The JSON response from GitHub API showing user information.
@@ -67,6 +52,7 @@ The JSON response from GitHub API showing user information.
 ### Save for Later
 
 1. Click the **"Save"** button in the header
+2. Select project
 2. Enter a name: `Get GitHub User`
 3. Click **"Save"**
 
@@ -74,7 +60,7 @@ The request is now saved to your project.
 
 ### Access Saved Requests
 
-1. Click the **hamburger menu**
+1. Click the project
 2. Your project shows saved requests
 3. Click a request to open it in a new tab
 
@@ -83,15 +69,10 @@ The request is now saved to your project.
 Every request you send is automatically saved to history.
 
 **View History:**
-1. Click the **"History"** button in the header bar
+1. Navigate to bottom history panel
 2. Browse past requests
 3. Click any entry to open it in a new tab
 
-**History includes:**
-- Request details (URL, method, headers, body)
-- Response details (status, headers, body, timing)
-- Timestamp
-
 ## Working with Tabs
 
 ### Multiple Tabs
@@ -105,46 +86,6 @@ Open multiple requests simultaneously:
 
 Unsaved changes are marked with a dot (•) on the tab label.
 
-## Next Example: POST Request
-
-Let's send some data to an API.
-
-### Step 1: New Request
-
-Create a new request tab (**Ctrl+T**)
-
-### Step 2: Configure POST Request
-
-**URL:**
-```
-https://httpbin.org/post
-```
-
-**Method:**
-```
-POST
-```
-
-**Headers:**
-```
-Content-Type: application/json
-```
-
-**Body:**
-1. Click the **"Body"** tab
-2. Select **"JSON"** syntax highlighting
-3. Enter JSON data:
-```json
-{
-  "name": "Test User",
-  "email": "test@example.com"
-}
-```
-
-### Step 3: Send and View
-
-Click **"Send"** and view the response. httpbin.org echoes back your request data.
-
 ## Common Request Types
 
 ### GET Request
@@ -183,35 +124,19 @@ Body: (none)
 
 ### Syntax Highlighting
 
-Roster automatically detects and highlights:
+Roster automatically detects and highlights JSON, XML, and HTML responses.
-- **JSON** responses
-- **XML** responses
-- **HTML** responses
 
-### Response Timing
+### Response Metrics
 
-View how long the request took:
+The status line shows status code, response time, and total size including headers:
 ```
-200 OK (1.23 seconds, 5.4 KB)
+200 OK 123 ms 5.4 KB
 ```
 
-### Response Size
-
-The status line shows the total response size including headers.
-
 ## Keyboard Shortcuts
 
 Essential shortcuts to speed up your workflow:
 
-| Action | Shortcut |
-|--------|----------|
-| New request | **Ctrl+T** |
-| Send request | **Ctrl+Return** |
-| Close tab | **Ctrl+W** |
-| Save request | **Ctrl+S** |
-| Switch tabs | **Ctrl+Tab** |
-| Quit | **Ctrl+Q** |
-
 See [[Keyboard-Shortcuts]] for the complete list.
 
 ## Next Steps
@@ -226,20 +151,6 @@ Now that you know the basics, explore more advanced features:
 
 ## Tips
 
-**Tip 1: Use httpbin.org for testing**
+- Use `httpbin.org` endpoints for testing (e.g., `https://httpbin.org/get`)
-- `https://httpbin.org/get` - Test GET requests
+- Save frequently used requests with descriptive names
-- `https://httpbin.org/post` - Test POST requests
+- Check history panel to review and compare past responses
-- `https://httpbin.org/headers` - See your request headers
-- `https://httpbin.org/delay/3` - Test timeouts
-
-**Tip 2: Save frequently used requests**
-- Save requests to projects for quick access
-- Use descriptive names: "Login", "Get User Profile", etc.
-
-**Tip 3: Use syntax highlighting**
-- Select JSON/XML/RAW in the body dropdown
-- Makes reading requests and responses much easier
-
-**Tip 4: Check the history**
-- History persists across sessions
-- Great for debugging or comparing responses

Home.md

@@ -4,18 +4,13 @@ Welcome to the **Roster** documentation! Roster is a modern HTTP client for GNOM
 
 ## What is Roster?
 
-Roster is a native GNOME application for testing and debugging HTTP APIs. It provides a clean, intuitive interface for:
+Roster is a native GNOME application for testing and debugging HTTP APIs with support for:
 
-- HTTP Requests - Send GET, POST, PUT, DELETE requests
+- HTTP requests (GET, POST, PUT, DELETE) with custom headers and bodies
-- Custom Headers & Bodies - Full control over request configuration
+- Project organization with environment variables
-- Response Viewing - View headers, body, status, and timing
+- Secure credential storage using GNOME Keyring
-- Request History - Persistent history with full request/response data
+- JavaScript preprocessing and postprocessing scripts
-- Project Organization - Organize requests into projects
+- Request history and export to cURL
-- Environment Variables - Manage different environments (dev, staging, prod)
-- Sensitive Variables - Secure storage of API keys and tokens in GNOME Keyring
-- JavaScript Scripts - Automate workflows with preprocessing/postprocessing
-- Export - Export requests to cURL and other formats
-- Beautiful UI - Native GNOME experience with libadwaita
 
 ## Quick Links
 
@@ -36,11 +31,6 @@ Roster is a native GNOME application for testing and debugging HTTP APIs. It pro
 - [[Keyboard-Shortcuts]] - Speed up your workflow
 - [[FAQ]] - Frequently asked questions
 
-### Development
-- [[Contributing]] - How to contribute to Roster
-- [[Development]] - Developer documentation
-- [[Architecture]] - Technical overview
-
 ## Key Features
 
 ### Secure Credential Storage

Installation.md

@@ -32,16 +32,12 @@ This method builds and installs Roster directly on your system.
 
 **Fedora:**
 ```bash
-sudo dnf install meson ninja-build gtk4-devel libadwaita-devel \
+sudo dnf install meson ninja-build gtk4-devel libadwaita-devel libsoup3-devel libsecret-devel gjs python3 gettext desktop-file-utils appstream
-                 libsoup3-devel libsecret-devel gjs python3 \
-                 gettext desktop-file-utils appstream
 ```
 
 **Ubuntu/Debian:**
 ```bash
-sudo apt install meson ninja-build libgtk-4-dev libadwaita-1-dev \
+sudo apt install meson ninja-build libgtk-4-dev libadwaita-1-dev libsoup-3.0-dev libsecret-1-dev gjs python3 gettext desktop-file-utils appstream
-                 libsoup-3.0-dev libsecret-1-dev gjs python3 \
-                 gettext desktop-file-utils appstream
 ```
 
 **Arch Linux:**
@@ -176,35 +172,17 @@ flatpak uninstall cz.bugsy.roster
 
 ## Troubleshooting
 
-### Build Errors
+**Build errors:**
+- "meson: command not found" → Install Meson
+- "Package not found" errors → Install missing development packages
 
-**Error: "meson: command not found"**
+**Runtime errors:**
-- Install Meson build system (see dependencies above)
+- "Failed to access Secret Service" → Ensure GNOME Keyring is unlocked
+- "Module 'gi' not found" → Install PyGObject
 
-**Error: "Package 'gtk4' not found"**
+**Flatpak:**
-- Install GTK 4 development files (see dependencies above)
+- "Nothing matches org.gnome.Platform" → Add Flathub remote and install GNOME SDK
-
+- No network access → Verify `--share=network` permission
-**Error: "Package 'libadwaita-1' not found"**
-- Install libadwaita development files (see dependencies above)
-
-### Runtime Errors
-
-**Error: "Failed to access Secret Service"**
-- Ensure GNOME Keyring is installed and unlocked
-- For Flatpak: Check that D-Bus permission is granted
-
-**Error: "Module 'gi' not found"**
-- Ensure PyGObject is installed: `sudo dnf install python3-gobject`
-
-### Flatpak Specific
-
-**Error: "error: Nothing matches org.gnome.Platform"**
-- Add Flathub remote: `flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo`
-- Install GNOME SDK: `flatpak install flathub org.gnome.Platform//49 org.gnome.Sdk//49`
-
-**Application doesn't have network access**
-- Check Flatpak permissions: `flatpak info --show-permissions cz.bugsy.roster`
-- Should include: `--share=network`
 
 ## Next Steps
 

Projects-and-Environments.md

@@ -19,10 +19,9 @@ Example projects:
 
 ### Creating a Project
 
-1. Click the **hamburger menu** (three lines) in top-left
+1. Click the "+" icon in top-left
-2. Select **"New Project"**
+2. Enter project name
-3. Enter project name
+3. Click **"Create"**
-4. Click **"Create"**
 
 A default "Default" environment is automatically created.
 
@@ -33,11 +32,11 @@ Projects appear in the sidebar on the left side:
 - Shows saved requests within the project
 - Active project highlighted
 
-### Renaming a Project
+### Editing a Project
 
-1. Right-click the project in sidebar
+1. Click the "three-dots" symbol near the project name in sidebar
-2. Select **"Rename"**
+2. Select **"Edit Project"**
-3. Enter new name
+3. Enter new name or click icon to choose from grid
 4. Click **"Save"**
 
 ### Deleting a Project
@@ -48,13 +47,6 @@ Projects appear in the sidebar on the left side:
 
 **Warning:** This deletes all requests, environments, and variables in the project!
 
-### Changing Project Icon
-
-1. Right-click the project in sidebar
-2. Select **"Change Icon"**
-3. Choose icon from grid
-4. Icon updates immediately
-
 ## Environments
 
 ### What is an Environment?
@@ -71,7 +63,8 @@ See [[Variables]] for complete environment and variable management documentation
 
 **Quick access:**
 1. Select a project
-2. Click **"Environments"** button in header bar
+2. Click the "three-dots" symbol near the project name in sidebar
+3. Click **"Manage Environments"
 3. Manage environments and variables in dialog
 
 ### Default Environment
@@ -88,138 +81,31 @@ Each project starts with a "Default" environment. You can:
 1. Configure your request (URL, method, headers, body)
 2. Click **"Save"** button in header
 3. Enter request name (e.g., "Get User Profile")
-4. Click **"Save"**
+4. Select a project
-
+5. Click **"Save"**
-Request is now saved to the current project.
 
 ### Opening a Saved Request
 
-1. Click the hamburger menu
+1. Navigate to your project
-2. Navigate to your project
+2. Click on a saved request
-3. Click on a saved request
+3. Request opens in a new tab
-4. Request opens in a new tab
 
 ### Editing a Saved Request
 
 1. Open the request
 2. Make changes
 3. Click **"Save"** (or Ctrl+S)
-4. Changes are saved
+4. Select Project and enter request name
+5. Click Save
 
 **Modified indicator:** Unsaved changes show a dot (•) on the tab label.
 
 ### Deleting a Saved Request
 
-1. Right-click the request in sidebar
+1. Click "x" icon near the request name in sidebar
-2. Select **"Delete"**
+2. Confirm deletion
-3. Confirm deletion
 
-### Attaching Scripts
+Requests can have preprocessing and postprocessing scripts attached. See [[Scripts]] for details.
-
-See [[Scripts]] for complete documentation.
-
-1. Save a request first
-2. Right-click the request in sidebar
-3. Select **"Edit Scripts"**
-4. Write preprocessing/postprocessing scripts
-5. Click **"Save"**
-
-## Switching Between Projects
-
-### In Sidebar
-
-Simply click different projects in the sidebar to view their contents.
-
-### Request Association
-
-Each request tab remembers its project:
-- Variables come from that project's environments
-- Saving updates that project
-
-## Organization Tips
-
-### Group by Service
-
-Create separate projects for each external API:
-```
-Projects:
-  GitHub API
-    - List Repositories
-    - Create Issue
-    - Get User
-  Stripe API
-    - Create Customer
-    - Create Payment
-    - List Charges
-```
-
-### Group by Feature
-
-Create projects for features in your app:
-```
-Projects:
-  Authentication
-    - Login
-    - Logout
-    - Refresh Token
-  User Management
-    - Create User
-    - Update Profile
-    - Delete Account
-```
-
-### Use Descriptive Names
-
-**Good request names:**
-- "Login with Email/Password"
-- "Get User Profile by ID"
-- "Create Payment Intent (Stripe)"
-- "Update User Settings"
-
-**Bad request names:**
-- "Request 1"
-- "Test"
-- "New Request"
-- "GET"
-
-## Project Workflow Example
-
-### Step 1: Create Project
-
-Create "My API" project
-
-### Step 2: Add Environments
-
-Open Environments dialog, add:
-- Production
-- Development
-
-### Step 3: Define Variables
-
-Add variables:
-- `base_url`
-  - Production: `https://api.example.com`
-  - Development: `http://localhost:3000`
-- `api_key` (mark as sensitive)
-  - Production: `prod-key-***`
-  - Development: `dev-key-***`
-
-### Step 4: Create Requests
-
-Create and save requests:
-- "Get Users" - `GET {{base_url}}/users`
-- "Create User" - `POST {{base_url}}/users`
-- "Delete User" - `DELETE {{base_url}}/users/{{user_id}}`
-
-### Step 5: Test Different Environments
-
-1. Open "Get Users" request
-2. Select "Development" environment
-3. Send (hits localhost)
-4. Select "Production" environment
-5. Send (hits production API)
-
-Same request, different targets!
 
 ## Data Storage
 

Scripts.md

@@ -38,31 +38,21 @@ Use cases:
 
 ## Adding Scripts to Requests
 
-### Step 1: Save a Request
+### Step 1: Open Script Editor
 
-Scripts are attached to saved requests.
+Use the Scripts tab in the request editor
 
-1. Configure your request
+The script editor tab contains two panels:
-2. Click **"Save"** button
+- **Preprocessing** panel
-3. Enter request name
+- **Postprocessing** panel
-4. Click **"Save"**
 
-### Step 2: Open Script Editor
+### Step 2: Write Your Script
 
-1. Right-click the saved request in the sidebar
+1. Select the appropriate panel
-2. Select **"Edit Scripts"**
-3. Script editor dialog opens with two tabs:
-   - **Preprocessing** tab
-   - **Postprocessing** tab
-
-### Step 3: Write Your Script
-
-1. Select the appropriate tab
 2. Write JavaScript code
 3. Click **"Save"** or **Ctrl+S**
-4. Close dialog
 
-### Step 4: Run Request with Scripts
+### Step 3: Run Request with Scripts
 
 1. Open the request
 2. Click **"Send"**
@@ -386,105 +376,33 @@ if (suggestedVersion) {
 
 ## Script Execution Flow
 
-When you click "Send" on a request with scripts:
+When sending a request with scripts:
-
+1. Execute preprocessing script (if present) - can modify request
-```
+2. Apply variable substitution (`{{variable_name}}`)
-1. Load request from UI
+3. Send HTTP request
-2. IF preprocessing script exists:
+4. Execute postprocessing script (if present) - can read response, set variables
-   2a. Execute preprocessing script
+5. Display response and save to history
-   2b. Script can modify request object
-   2c. Script output shown in "Preprocessing" tab
-3. Apply variable substitution ({{variable_name}})
-4. Send HTTP request
-5. Receive response
-6. IF postprocessing script exists:
-   6a. Execute postprocessing script
-   6b. Script can read response, set variables
-   6c. Script output shown in "Postprocessing" tab
-7. Display response in UI
-8. Save to history
-```
 
 ## Error Handling
 
-### Script Errors
+If a script throws an error, the error is shown in the script output panel. The request still executes (preprocessing) or response still displays (postprocessing). Variable changes before the error are preserved.
-
-If a script throws an error:
-- Error message shown in script results tab
-- Request still executes (preprocessing) or response still displays (postprocessing)
-- Variable changes before the error are preserved
-
-### Example: Safe JSON Parsing
 
+Always use try-catch for JSON parsing:
 ```javascript
 try {
     const data = JSON.parse(response.body);
     roster.setVariable('user_id', data.user.id);
-    console.log('Success');
 } catch (e) {
-    console.error('Failed to parse JSON:', e.message);
+    console.error('Parse error:', e.message);
 }
 ```
 
 ## Best Practices
 
-### Keep Scripts Simple
+- **Keep scripts simple** - One clear purpose per script
-
+- **Handle errors** - Use try-catch for JSON parsing and check status codes
-Scripts should be short and focused:
+- **Use logging** - Track execution with console.log for debugging
-- One clear purpose per script
+- **Never log secrets** - Log confirmations, not actual token/key values
-- Avoid complex logic
-- Use console.log for debugging
-
-### Error Handling
-
-Always handle potential errors:
-```javascript
-if (response.statusCode === 200) {
-    try {
-        const data = JSON.parse(response.body);
-        // ... process data
-    } catch (e) {
-        console.error('Parse error:', e.message);
-    }
-} else {
-    console.error('Request failed:', response.statusText);
-}
-```
-
-### Variable Naming
-
-Use clear, descriptive variable names:
-```javascript
-// Good
-roster.setVariable('github_access_token', token);
-roster.setVariable('user_profile_id', id);
-
-// Bad
-roster.setVariable('token', token);
-roster.setVariable('id', id);
-```
-
-### Logging
-
-Use console output to track script execution:
-```javascript
-console.log('Starting authentication...');
-// ... authentication logic
-console.log('Authentication complete');
-```
-
-### Sensitive Data
-
-**Never log sensitive data:**
-```javascript
-// BAD - logs the actual token
-const token = roster.getVariable('api_key');
-console.log('Token:', token);
-
-// GOOD - confirms without revealing
-const token = roster.getVariable('api_key');
-console.log('Token retrieved');
-```
 
 ## Limitations
 
@@ -513,37 +431,9 @@ Scripts cannot:
 
 ## Debugging Scripts
 
-### Use Console Output
+- Use console.log liberally to track script execution
-
+- Check Preprocessing/Postprocessing panels for output and errors
-Liberally use console.log:
+- Start with simple test scripts and build up complexity
-```javascript
-console.log('Request URL before:', request.url);
-// ... modify URL
-console.log('Request URL after:', request.url);
-```
-
-### Check Script Results
-
-After sending request:
-1. Look for "Preprocessing" tab (if preprocessing script exists)
-2. Look for "Postprocessing" tab (if postprocessing script exists)
-3. View console output and any errors
-
-### Test with Simple Scripts
-
-Start simple and build up:
-```javascript
-// Test 1: Verify script runs
-console.log('Script is running!');
-
-// Test 2: Verify variable access
-const baseUrl = roster.getVariable('base_url');
-console.log('Base URL:', baseUrl);
-
-// Test 3: Verify request modification
-request.headers['X-Test'] = 'hello';
-console.log('Added test header');
-```
 
 ## Next Steps
 

Sensitive-Variables.md

@@ -36,41 +36,29 @@ Content: "secret-abc123-visible-to-all"  (encrypted at rest)
 
 ## Usage
 
-### Step 1: Open Environments Dialog
+### Mark Variable as Sensitive
 
-1. Select your project from the sidebar
+Open the Environments dialog for your project.
-2. Click the **"Environments"** button in the header bar
-3. The variables table appears
 
-### Step 2: Identify the Lock Icon
+Each variable row has a **lock icon** to toggle between secure/insecure storage.
-
-Each variable row has three buttons:
-- Variable name entry
-- **Lock icon** (toggle between secure/insecure storage)
-- Delete button (trash icon)
-
-### Step 3: Mark Variable as Sensitive
 
 **Before entering secrets (recommended):**
 1. Create variable (e.g., `api_key`)
-2. Click the **lock icon** (appears as unlocked/gray initially)
+2. Click the **lock icon** - it changes to locked state
-3. Icon changes to locked state (with accent color)
+3. Variable name becomes bold and colored
-4. Variable name becomes bold and colored
+4. Enter your secret value
-5. Now enter your secret value
 
 **After entering secrets (migration):**
 1. Click the lock icon on existing variable
 2. Values automatically move from JSON to keyring
-3. JSON file now contains empty placeholders
 
-### Step 4: Enter Secret Values
+### Enter Secret Values
 
-1. Click in the value entry field
+Values in sensitive variables:
-2. Type your secret value
+- Display as bullets (••••••) instead of characters
-3. **You'll see bullets (••••••) instead of characters**
+- Automatically save to GNOME Keyring (encrypted)
-4. Value automatically saves to GNOME Keyring (encrypted)
 
-### Step 5: Use in Requests
+### Use in Requests
 
 Sensitive variables work exactly like regular variables:
 
@@ -85,62 +73,11 @@ When you send the request:
 3. Substitutes it into the request
 4. Sends the request with the real value
 
-## Visual Indicators
-
-### Lock Icon States
-
-**Unlocked (channel-insecure-symbolic):**
-- Gray/inactive appearance
-- Variable stored in plain JSON
-- Tooltip: "Not sensitive (stored in JSON) - Click to mark as sensitive"
-
-**Locked (channel-secure-symbolic):**
-- Colored/active appearance (accent color)
-- Variable stored in encrypted keyring
-- Tooltip: "Sensitive (stored in keyring) - Click to make non-sensitive"
-
-### Variable Name Styling
-
-**Regular variables:**
-- Normal text color
-- Normal font weight
-
-**Sensitive variables:**
-- Accent color (theme-dependent)
-- Bold font weight
-- Easy to identify at a glance
-
-### Value Entry Fields
-
-**Regular variables:**
-- Show typed characters normally
-- Standard text entry
-
-**Sensitive variables:**
-- Show bullets (••••••) like password fields
-- Entry purpose: PASSWORD
-- Cannot see the value while typing
-
 ## Viewing Secrets in Keyring
 
-To verify your secrets are encrypted:
+Open "Passwords and Keys" (Seahorse) and navigate to "Login" keyring. Look for entries labeled `Roster: ProjectName/EnvironmentName/VariableName`.
 
-1. Open **"Passwords and Keys"** application (Seahorse)
+You can view, edit, or delete secrets from Seahorse (requires authentication).
-2. Navigate to **"Login"** keyring
-3. Look for entries labeled: `Roster: ProjectName/EnvironmentName/VariableName`
-
-Example:
-```
-Login Keyring
-  Roster: GitHub API/Production/api_token
-  Roster: GitHub API/Development/api_token
-  Roster: Stripe API/Production/secret_key
-```
-
-Click any entry to:
-- View the secret value (requires authentication)
-- Edit the value manually
-- Delete the secret
 
 ## Making Variables Non-Sensitive
 
@@ -155,92 +92,14 @@ If you marked a variable as sensitive by mistake:
 
 ## Security
 
-### Encryption
+- Encrypted at rest with your GNOME login password
-
+- Keyring unlocks automatically on login
-- Values encrypted at rest with your GNOME login password
+- Only accessible by your user account
-- Uses same encryption as system passwords
+- Flatpak requires explicit permission
-- No plaintext secrets in file system
-
-### Auto-Unlock
-
-- Keyring unlocks automatically when you log in
-- No need to enter password again
-- Locked when you log out
-
-### Access Control
-
-- Only your user account can access
-- Protected by OS-level security
-- Sandboxed apps (Flatpak) require explicit permission
-
-### Separation
-
-Roster secrets are stored with a custom schema:
-- Schema: `cz.bugsy.roster.EnvironmentVariable`
-- Attributes: `project_id`, `environment_id`, `variable_name`
-- **Won't clutter your personal passwords**
-- Easy to identify in Seahorse
-
-## Best Practices
-
-### DO Mark as Sensitive
-
-- **API keys**: `api_key`, `github_token`, `stripe_key`
-- **Passwords**: `password`, `db_password`, `admin_pass`
-- **Tokens**: `bearer_token`, `oauth_token`, `access_token`
-- **Secrets**: `client_secret`, `api_secret`, `webhook_secret`
-- **Private keys**: Any cryptographic keys
-
-### DON'T Mark as Sensitive
-
-- **URLs**: `base_url`, `api_endpoint`, `webhook_url`
-- **Configuration**: `timeout`, `max_retries`, `api_version`
-- **Identifiers**: `env`, `region`, `datacenter`, `tenant_id`
-- **Non-secret data**: Anything that's OK to be visible
-
-### Workflow Tips
-
-**Create variables first, then mark as sensitive:**
-```
-1. Add variable "api_key"
-2. Click lock icon (mark as sensitive)
-3. Enter value (goes to keyring immediately)
-```
-
-**Use descriptive names:**
-```
-Good: github_personal_token, stripe_secret_key
-Bad: token1, key, secret
-```
-
-**Group related variables:**
-```
-base_url          (regular)
-api_key           (sensitive)
-api_secret        (sensitive)
-timeout           (regular)
-```
 
 ## Automatic Cleanup
 
-When you delete variables, environments, or projects, Roster automatically cleans up keyring secrets:
+Roster automatically removes keyring secrets when you delete variables, environments, or projects. Renamed variables are also automatically updated in the keyring.
-
-**Delete variable:**
-- Removed from JSON
-- All keyring secrets for that variable deleted (across all environments)
-
-**Delete environment:**
-- Removed from JSON
-- All keyring secrets for that environment deleted
-
-**Delete project:**
-- Project removed from disk
-- **All keyring secrets for that project deleted**
-
-**Rename variable:**
-- Variable renamed in JSON
-- All keyring secrets automatically renamed
-- No data loss
 
 ## Script Integration
 
@@ -270,105 +129,22 @@ Scripts don't need to know whether variables are sensitive - storage is handled
 
 ## Troubleshooting
 
-### Keyring Not Unlocked
+**Keyring not unlocked:**
+- Ensure you're logged into GNOME (keyring unlocks automatically)
+- Manual unlock: Open Seahorse, right-click "Login", select "Unlock"
 
-**Symptom:** Error accessing secrets
+**Flatpak permission denied:**
+- Verify `cz.bugsy.roster.json` includes `--talk-name=org.freedesktop.secrets`
+- Check: `flatpak info --show-permissions cz.bugsy.roster`
 
-**Solution:**
+**Secrets missing after reinstall:**
-1. Ensure you're logged into GNOME
+- Keyring persists across installs - check Seahorse under "Login" keyring
-2. Keyring unlocks automatically on login
-3. Manual unlock: Open "Passwords and Keys", right-click "Login", select "Unlock"
 
-### Flatpak Permission Denied
+## Platform Notes
 
-**Symptom:** Cannot access keyring from Flatpak
+Both native and Flatpak installations use the same system keyring. Secrets work across install methods.
 
-**Solution:**
+Flatpak requires D-Bus permission: `--talk-name=org.freedesktop.secrets`
-1. Check `cz.bugsy.roster.json` includes: `--talk-name=org.freedesktop.secrets`
-2. Rebuild Flatpak with correct permissions
-3. Verify: `flatpak info --show-permissions cz.bugsy.roster`
-
-### Cannot View Secret in Seahorse
-
-**Symptom:** Secret exists but won't display
-
-**Solution:**
-1. Right-click the secret in Seahorse
-2. Select "Show password"
-3. Enter your login password when prompted
-
-### Lost Secrets After Reinstall
-
-**Symptom:** Secrets missing after reinstalling Roster
-
-**Keyring persists across installs** - secrets should still be there.
-
-**Check:**
-1. Open Seahorse
-2. Look under "Login" keyring
-3. Search for "Roster:"
-
-If missing, you'll need to re-enter them.
-
-## Advanced: Manual Keyring Management
-
-You can manually manage Roster secrets using Seahorse:
-
-### View All Roster Secrets
-
-1. Open Seahorse
-2. Navigate to "Login" keyring
-3. Search or filter for: `Roster`
-4. All Roster secrets appear
-
-### Backup Secrets
-
-Seahorse can export keyring for backup:
-1. File → Export
-2. Select secrets to export
-3. Choose secure location
-
-### Delete All Roster Secrets
-
-1. Search for "Roster" in Seahorse
-2. Select all Roster entries
-3. Right-click → Delete
-
-## Migration from Plain Variables
-
-If you have existing projects with secrets in plain text:
-
-```javascript
-// Step 1: Identify secrets in your variables
-// Look for: api_key, password, token, secret, private_key
-
-// Step 2: For each secret variable:
-// - Open Environments dialog
-// - Click lock icon
-// - Values automatically move to keyring
-
-// Step 3: Verify in Seahorse
-// - Open "Passwords and Keys"
-// - Check secrets appear under "Login" keyring
-```
-
-Your JSON file will now have empty strings, and secrets are encrypted.
-
-## Platform Differences
-
-### Native Installation
-
-- Keyring: `~/.local/share/keyrings/`
-- Direct access to system keyring
-- No special permissions needed
-
-### Flatpak Installation
-
-- Keyring: Same system keyring (shared)
-- Requires D-Bus permission: `--talk-name=org.freedesktop.secrets`
-- Sandboxed but can access keyring with permission
-
-Both installations share the same keyring - secrets work across install methods!
 
 ## Next Steps
 

Variables.md

@@ -34,11 +34,12 @@ Each project can have multiple environments, and each environment has its own se
 ### Step 1: Open Environments Dialog
 
 1. Select a project from the sidebar
-2. Click the **"Environments"** button in the header bar
+2. Click the "Three-Dots" button near the project name
+3. Select **"Manage Environments"**
 
 ### Step 2: Add Environment
 
-1. Click **"Add Environment"** button
+1. Click **+** button near Environments
 2. Enter name (e.g., "Production", "Development")
 3. Click **"Add"**
 
@@ -61,7 +62,7 @@ Click in the cells to enter values for each environment:
 | base_url | `https://api.example.com` | `http://localhost:3000` |
 | timeout  | `30` | `60` |
 
-Click **"Done"** to save.
+Close Manage Environments table to save.
 
 ## Using Variables in Requests
 
@@ -93,17 +94,16 @@ Variables work in:
 
 ### Rename Variable
 
-1. Open **Environments** dialog
+1. Open **Manage Environments** dialog
 2. Click on variable name
 3. Edit the name
-4. Press Enter
 
 The variable is renamed across all environments automatically.
 
 ### Delete Variable
 
 1. Open **Environments** dialog
-2. Click the **trash icon** next to variable name
+2. Click the **x** next to variable name
 3. Confirm deletion
 
 The variable is removed from all environments.
@@ -127,55 +127,12 @@ All variable values for that environment are deleted.
 
 ## Common Variable Patterns
 
-### Base URL
+Common variables to define across environments:
-
+- `base_url` - API base URL (e.g., `https://api.example.com` vs `http://localhost:3000`)
-```
+- `api_version` - API version (e.g., `v2` vs `v2-beta`)
-Variable: base_url
+- `timeout` - Request timeout values
-Production: https://api.example.com
+- `env` - Environment identifier for headers
-Development: http://localhost:3000
+- `test_user_id` - Test data IDs
-
-Usage: {{base_url}}/users/123
-```
-
-### API Version
-
-```
-Variable: api_version
-Production: v2
-Development: v2-beta
-
-Usage: {{base_url}}/{{api_version}}/users
-```
-
-### Timeout Values
-
-```
-Variable: timeout
-Production: 30
-Development: 60
-
-Usage: X-Timeout: {{timeout}}
-```
-
-### Environment Identifier
-
-```
-Variable: env
-Production: prod
-Development: dev
-
-Usage: X-Environment: {{env}}
-```
-
-### User ID for Testing
-
-```
-Variable: test_user_id
-Production: 12345
-Development: 1
-
-Usage: {{base_url}}/users/{{test_user_id}}
-```
 
 ## Script Integration
 
@@ -231,123 +188,26 @@ Scripts automatically update variables in the currently selected environment.
 
 ## Best Practices
 
-### Use Descriptive Names
+- **Keep environments consistent** - All environments should have the same variable names with different values
-
+- **Use sensitive variables for secrets** - Never store API keys, passwords, or tokens in regular variables (they're plain text). Use [[Sensitive-Variables]] instead
-Good:
-- `base_url`
-- `api_key`
-- `github_token`
-- `stripe_secret_key`
-
-Bad:
-- `url1`
-- `key`
-- `token`
-
-### Group Related Variables
-
-```
-# API Configuration
-base_url
-api_version
-timeout
-
-# Authentication
-api_key
-api_secret
-auth_token
-
-# Test Data
-test_user_id
-test_email
-```
-
-### Keep Environments Consistent
-
-All environments should have the same variable names with different values:
-
-| Variable | Production | Development |
-|----------|-----------|-------------|
-| base_url | `api.example.com` | `localhost:3000` |
-| api_key  | `prod-key-***` | `dev-key-***` |
-| timeout  | `30` | `60` |
-
-### Use Sensitive Variables for Secrets
-
-**DO NOT** store secrets in regular variables - they are saved in plain text!
-
-Use [[Sensitive-Variables]] instead:
-- API keys
-- Passwords
-- Tokens
-- Secret keys
 
 ## Undefined Variables
 
-When Roster encounters `{{variable_name}}` but the variable is not defined:
+When `{{variable_name}}` is not defined in the current environment:
+- Entry field is highlighted with warning color
+- The literal text `{{variable_name}}` is sent in the request
 
-**Visual Warning:**
+To fix, add the variable in the Environments dialog.
-- The entry field with undefined variable is highlighted
-- Warning color indicates missing variable
-
-**Request Behavior:**
-- The literal text `{{variable_name}}` is sent
-- No error is thrown
-- Check the console for warnings
-
-**Fix:**
-1. Open **Environments** dialog
-2. Add the missing variable
-3. Set its value in current environment
 
 ## Environment Switching
 
-Switch environments to test the same request against different APIs:
+Use the environment dropdown to test the same request against different targets. For example, `GET {{base_url}}/users` will hit `localhost:3000/users` in Development or `api.example.com/users` in Production.
-
-**Example Workflow:**
-1. Create request: `GET {{base_url}}/users`
-2. Select "Development" environment
-3. Send request (goes to `http://localhost:3000/users`)
-4. Select "Production" environment
-5. Send request (goes to `https://api.example.com/users`)
-
-Same request, different targets!
 
 ## Advanced Topics
 
-### Variables in Request Body
+- **Variables in JSON body** - Use `{{variable}}` syntax. Remove quotes for numeric values
-
+- **Nested variables** - Variables can reference other variables (e.g., `{{base_url}}/{{api_version}}`)
-```json
+- **Script-created variables** - Scripts can create variables with `roster.setVariable()`
-{
-  "api_key": "{{api_key}}",
-  "environment": "{{env}}",
-  "user_id": {{user_id}}
-}
-```
-
-Note: Numeric values should not have quotes if you want them as numbers.
-
-### Nested Variable References
-
-Variables can contain other variables:
-```
-Variable: full_url
-Value: {{base_url}}/{{api_version}}/users
-```
-
-Both `{{base_url}}` and `{{api_version}}` will be substituted.
-
-### Dynamic Variables from Scripts
-
-Variables don't have to be manually created - scripts can create them:
-
-```javascript
-// Preprocessing script
-const timestamp = new Date().toISOString();
-roster.setVariable('request_timestamp', timestamp);
-
-// Now you can use {{request_timestamp}} in the request
-```
 
 ## Next Steps