From a46794b386afeb83ae659a11554858796ad16bc3 Mon Sep 17 00:00:00 2001
From: jtmorris <john@jtmorris.net>
Date: Fri, 22 May 2026 06:06:14 +0000
Subject: [PATCH] Better scoped semicolon coding style.

---
 AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index dffd776..eba23a2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -83,15 +83,59 @@ while (myvar)
 while (myvar) do_action();
 ```
 
-### 2. **ALWAYS** Use Semicolons to End Statements
+### 2. ALWAYS Terminate JavaScript Statements with Semicolons
 
-For maximum clarity and readability, always end lines using semicolons. 
+ALWAYS end every JavaScript statement with a semicolon (;).
 
-**GOOD** Example:
+Rationale: Semicolons make intent explicit, eliminate ASI surprises, improve readability, and produce clearer diffs and tooling output.
+
+Scope:
+    - Applies to all JavaScript statements — inside signal handlers (onClicked: { ... }), custom methods (function foo() { ... }), arrow function bodies, standalone .js files, and test files.
+    - Does NOT apply to QML declarative property bindings (width: 100, text: "foo", anchors.centerIn: parent, model: myModel, etc.). These are not statements; adding ; after them is either a syntax error or non-idiomatic in QML.
+    - When multiple QML bindings are written on a single line for compactness, ; is used only as a separator between bindings (Qt/QML convention), not as a statement terminator.
+
+GOOD (JavaScript statements):
 ```javascript
-do_action();
+// Inside a QML signal handler or method
+onClicked: {
+    root.toggleTailscale();
+    ToastService.showInfo("Toggled");
+}
+function buildCommand(hostname) {
+    if (hostname === "") {
+        return ["tailscale", "set", "--exit-node="];
+    }
+    return ["tailscale", "set", "--exit-node=" + hostname];
+}
 ```
-**BAD** Example:
+
 ```javascript
-do_action()
+// In a .js file
+if (!peerMap) {
+    return [];
+}
+return Object.keys(peerMap).map(...);
+```
+
+BAD (missing semicolons on statements):
+```javascript
+if (condition) {
+    doAction()
+}
+return value
+```
+
+BAD (incorrect semicolon on QML binding — never do this):
+```javascript
+width: 360;           // OK (separator on same line)
+height: 400;          // WRONG — this is a binding, not a statement
+text: "Tailscale";    // WRONG
+```
+
+GOOD (correct QML binding style):
+```javascript
+width: 360
+height: 400
+text: "Tailscale"
+Item { width: 1; height: 1; Layout.fillWidth: true }   // ; only as separator
 ```
\ No newline at end of file