Feature/agent friendly

.claude/control/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: control
+description: "Control the Geany editor UI from the agent terminal — open files, save, scroll to changes, refresh the file tree"
+argument-hint: "<command> [args] | save-all | refresh | open <path> | scroll <path>:<line> | list"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+<objective>
+Drive the live Geany editor from within this agent session using the geanycontrol plugin.
+
+This skill lets the agent:
+- Save open files before starting work so Geany does not prompt about conflicts
+- Open files the agent just created or modified
+- Scroll Geany to the exact line of a change
+- Refresh the treebrowser after adding or deleting files on disk
+- Query which files are currently open
+- Trigger Tools-menu items by name
+
+All operations go through the geany-ctrl script which talks to the
+geanycontrol Unix socket at ~/.config/geany/geanycontrol.sock.
+The plugin must be loaded in the running Geany instance.
+</objective>
+
+<context>
+## Socket path
+
+    ~/.config/geany/geanycontrol.sock
+    (expands to: $XDG_CONFIG_HOME/geany/geanycontrol.sock if XDG_CONFIG_HOME is set)
+
+## geany-ctrl script location (in this repo)
+
+    /home/teknopaul/github_workspace/geany-plugins/geanycontrol/geany-ctrl
+
+Add it to PATH or call it with the full path.  Requires `socat` at runtime.
+
+## Availability check
+
+Before sending commands, verify the plugin is running:
+
+    printf 'ping\n' | socat - UNIX-CONNECT:$HOME/.config/geany/geanycontrol.sock
+
+If the socket does not exist, Geany is not running or the GeanyControl
+plugin is not loaded — skip UI operations, they are not required for the
+work to succeed.
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `ping` | Liveness check; always replies `ok` |
+| `save-all` | Save every unsaved open document |
+| `save-file <path>` | Save one specific document |
+| `open-file <path>` | Open a file in the editor |
+| `close-file <path>` | Close a document (unsaved ch1nges are discarded) |
+| `scroll-to-line <path>:<line>` | Open file and jump to line (1-based) |
+| `get-current-file` | Return the path of the currently active document |
+| `list-open-files` | Return newline-separated list of all open file paths |
+| `activate-menu-item <label>` | Activate a Tools-menu item by label (case-insensitive) |
+| `refresh` | Signal treebrowser to reload the file tree |
+
+## geany-ctrl usage
+
+    geany-ctrl ping
+    geany-ctrl save-all
+    geany-ctrl open-file /path/to/file.c
+    geany-ctrl close-file /path/to/file.c
+    geany-ctrl save-file /path/to/file.c
+    geany-ctrl scroll-to-line /path/to/file.c:42
+    geany-ctrl get-current-file
+    geany-ctrl list-open-files
+    geany-ctrl activate-menu-item "Agent Tools"
+    geany-ctrl refresh
+
+## Raw socat usage (no script dependency)
+
+    SOCK="$HOME/.config/geany/geanycontrol.sock"
+    echo "save-all"          | socat - "UNIX-CONNECT:$SOCK"
+    echo "refresh"           | socat - "UNIX-CONNECT:$SOCK"
+    echo "open-file /tmp/x"  | socat - "UNIX-CONNECT:$SOCK"
+
+## Inter-plugin signal API (C code only)
+
+Other plugins can drive geanycontrol without going through the socket by
+emitting signals on `geany->object`:
+
+    g_signal_emit_by_name(geany->object, "geanycontrol-open-file", path);
+    g_signal_emit_by_name(geany->object, "geanycontrol-close-file", path);
+    g_signal_emit_by_name(geany->object, "geanycontrol-save-file", path);
+    g_signal_emit_by_name(geany->object, "geanycontrol-save-all");
+    g_signal_emit_by_name(geany->object, "geanycontrol-scroll-to-line", "path:42");
+    g_signal_emit_by_name(geany->object, "geanycontrol-activate-menu-item", label);
+    g_signal_emit_by_name(geany->object, "geanycontrol-refresh");
+
+Check the signal exists before emitting (geanycontrol may not be loaded):
+
+    if (g_signal_lookup("geanycontrol-open-file", G_OBJECT_TYPE(geany->object)))
+        g_signal_emit_by_name(geany->object, "geanycontrol-open-file", path);
+
+## treebrowser refresh wiring
+
+treebrowser.c already connects to "geanycontrol-refresh" in plugin_init —
+no extra code needed.  If geanycontrol is loaded before treebrowser, the
+connection happens automatically.  If treebrowser loads first, the signal
+lookup returns 0 and the connection is skipped (harmless; refresh will
+still emit the signal but nothing will be connected).
+</context>
+
+<process>
+Determine what the user (or prior task) needs done with the Geany UI, then
+execute the minimal set of geany-ctrl commands to accomplish it.
+
+## Step 1 — Check availability
+
+    SOCK="$HOME/.config/geany/geanycontrol.sock"
+    if [ ! -S "$SOCK" ]; then
+        # Geany not running or plugin not loaded — skip UI steps, note in output
+        exit 0
+    fi
+
+## Step 2 — Common workflow patterns
+
+### Before starting work on files Geany has open
+
+    geany-ctrl save-all
+
+This prevents "file changed on disk" prompts while the agent edits files.
+
+### After editing or creating files
+
+    geany-ctrl refresh
+
+This reloads the treebrowser so newly created or deleted files appear
+immediately.
+
+### Open a specific file
+
+    geany-ctrl open-file /path/to/changed-file.c
+
+### Jump to a specific line (e.g., where a bug was fixed)
+
+    geany-ctrl scroll-to-line /path/to/changed-file.c:42
+
+### Full post-edit sequence
+
+    geany-ctrl refresh
+    geany-ctrl open-file /path/to/changed-file.c
+    geany-ctrl scroll-to-line /path/to/changed-file.c:42
+
+### Query what is open before deciding what to close
+
+    geany-ctrl list-open-files
+
+## Step 3 — Report result
+
+If any command returns a line starting with `error:`, report it to the user.
+`ok` responses can be silently swallowed unless the user asked for verbose output.
+
+## Error handling
+
+- Socket missing → note "GeanyControl not available" and continue without UI steps.
+- `error: could not open file` → the path does not exist; verify the path before retrying.
+- `error: menu item not found` → the label did not match; check the exact label text
+  in Geany's Tools menu.
+- `socat` not installed → install it (`sudo apt install socat`) or use the raw
+  printf/socat one-liner pattern from the context section above.
+</process>

.claude/skills/c-bash/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: c-bash
+description: make .sh files follow common C code conventions for readability and maintainability
+allowed-tools: bash
+---
+
+All `.sh` files should follow `.claude/skills/bash-coding-standards.md`
+
+You MUST work on one file at a time, don't do bulk updates since these tend to break scripts subtly.
+
+When replacing `"${var}"` it is _not_ always safe to use `$var`, especially if the variable might contain spaces or unknown input.
+
+It is only safe to use the shortened `$var` syntax when the variable is known to be a simple string value, usually that means its set earlier in the script.
+
+It is also only safe to remove the `{}` if the use of this variable does not cause ambiguity, or if the text following it does not cause bash to interpret it as a different variable.
+
+After making changes to each file one at a time you must `bash -n` the changed script and then run the script to make sure it still works.
+
+## converting non-compliant code
+
+When asked to convert bash to to these conventions...
+
+Never do mass sed/perl replacements across many files at once.
+
+Each change must be read in context first. A variable that looks like a path may hold multi-line output, quoted strings, or JSON. The fix that is correct for one variable may silently corrupt another.
+
+Quotes are load-bearing — check usage before removing them
+"$var" is NOT just style. It is required when:
+- the variable may contain spaces (file names, URLs with query strings, response bodies)
+- the variable may contain newlines (curl response bodies, grep output)
+- the variable may contain glob characters (*, ?, [)
+- the variable is on the right-hand side of [[ ]] and could contain * or ?
+
+- Only remove quotes when you can see, from reading the script, that none of these apply.
+echo "$var" must stay quoted when var is a response body
+echo $var word-splits and glob-expands. echo "$var" preserves newlines. Any variable holding HTTP response bodies, JSON, or log output must keep quotes.
+
+Work iteratively — one file at a time
+
+1. Read the full file
+1. Identify violations
+1. Understand each variable's content and all its usages
+1. Make targeted changes
+1. Run bash -n and the test before moving to the next file
+
+Never use automated tools (sed/perl/python) to rename variables across files
+
+Variable names are not unique tokens — $body in one script is a response body requiring quotes; in another it is a simple path. Mass rename without reading context will introduce bugs.
+The rule is: remove ${braces} only, not quotes
+
+"${foo}" → "$foo" is usually safe (keeps quotes, removes unnecessary braces).
+If any code uses "${foo}_baa" changing to  "$foo_bar" is not safe.
+
+"${foo}" → $foo is only safe after reading the specific usage.

.claude/skills/c-bash/bash-coding-standards.md

@@ -0,0 +1,43 @@
+# Bash coding standards
+
+All test `.sh` scripts should follow these guidelines.
+
+follow [bash code style](bash-code-style.md).
+
+
+Presume no spaces in paths, this is Linux, no need to quote them.
+Presume URLs do not have spaces, they never do, no need to quote them.
+Don't quote `$port` variables
+Don't use colors `${RED}` outside of the test utilities.
+Avoid env vars for nodejs server parameters, use CLI args.
+
+Make use of test utilities `test-functions.sh` and `integration-test-fucntion.sh`, do not write script specific
+
+- assertions
+- kill functions
+
+Finish scripts with `test_summary` this will exit in a way that integrates with Makefile test targets.
+For nginx integration tests just before `test_summary` run `crash_check`
+
+## exit handlers
+
+Handle cleanup in an exit handler, that runs in success or failure scenario.
+```
+cleanup() {
+  cleanup_nginx
+  cleanup_pid $backend_pid
+  cleanup_temp_dir
+}
+trap cleanup EXIT
+```
+
+# Prefer standard ports
+
+mxsrv           53880
+legacy          8080
+winchecker-next 9090
+cache_manager   9999
+
+# preferred vars
+
+base_url