feat: add configuration system with JSONC support

.github/workflows/test.yml

@@ -2,9 +2,9 @@ name: Test
 
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
-    branches: [master]
+    branches: [main]
 
 jobs:
   test:

README.md

@@ -58,6 +58,86 @@ Transient hints auto-clear in two ways:
 
 Hints are **session-scoped** (each session has its own) and **project-scoped** (stored under a hash of the project directory). All data lives in `~/.cache/opencode/btw/`. Hint files are cleaned up automatically when sessions are deleted.
 
+## Configuration
+
+The plugin works out of the box with no configuration. All options below are optional — only add what you want to change.
+
+### Config files
+
+Configuration is loaded from two locations, merged in order (later overrides earlier):
+
+| Layer      | Path                              | Purpose              |
+| ---------- | --------------------------------- | -------------------- |
+| **Global** | `~/.config/opencode/btw.jsonc`    | User-wide defaults   |
+| **Project** | `.opencode/btw.jsonc` (walks up) | Per-project overrides |
+
+The global config file is auto-created on first run with a `$schema` reference for IDE auto-completion. Files use JSONC format (JSON with comments and trailing commas).
+
+You can also use `XDG_CONFIG_HOME` to customize the global config location: `$XDG_CONFIG_HOME/opencode/btw.jsonc`.
+
+### Options
+
+```jsonc
+{
+  // JSON Schema for IDE auto-completion
+  "$schema": "https://raw.githubusercontent.com/kldzj/opencode-btw/main/btw.schema.json",
+
+  // Default hint type: false = transient (auto-clears), true = pinned (persists)
+  "defaultPinned": false,
+
+  // Auto-clear behavior for transient hints
+  "autoClear": {
+    "onIdle": true,           // Clear when session goes idle
+    "onQuestionTool": true    // Clear when the question tool fires
+  },
+
+  // Hint injection settings
+  "injection": {
+    "target": "both",                  // "both", "system", or "user"
+    "systemPromptPosition": "prepend", // "prepend" or "append"
+    "systemInstructions": null,        // Custom framing text (null = built-in default)
+    "userMessagePrefix": "BTW, "       // Prefix for single-hint user messages
+  },
+
+  // Enable debug mode (verbose toast logging)
+  "debug": false,
+
+  // Default toast notification duration in milliseconds
+  "toastDuration": 3000
+}
+```
+
+### Examples
+
+**Pinned hints by default** — skip typing `pin` every time:
+
+```jsonc
+{ "defaultPinned": true }
+```
+
+**System prompt only** — don't modify user messages:
+
+```jsonc
+{ "injection": { "target": "system" } }
+```
+
+**Custom framing** — change how hints are presented to the model:
+
+```jsonc
+{
+  "injection": {
+    "systemInstructions": "The user has set the following preferences. Follow them strictly.",
+    "userMessagePrefix": "Note: "
+  }
+}
+```
+
+**Disable auto-clear on idle** — only clear when the question tool fires:
+
+```jsonc
+{ "autoClear": { "onIdle": false } }
+```
+
 ## Use cases
 
 - **Error loops**: the model keeps making the same mistake — `/btw you're using the wrong API, check the docs for v2`

btw.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "opencode-btw Configuration",
+  "description": "Configuration for the opencode-btw hint injection plugin",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for IDE auto-completion"
+    },
+    "defaultPinned": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether newly added hints are pinned (persistent) by default. When false, hints are transient and auto-clear after the model turn."
+    },
+    "autoClear": {
+      "type": "object",
+      "description": "Controls when transient hints are automatically cleared",
+      "additionalProperties": false,
+      "properties": {
+        "onIdle": {
+          "type": "boolean",
+          "default": true,
+          "description": "Auto-clear transient hints when the session goes idle (model finishes responding)"
+        },
+        "onQuestionTool": {
+          "type": "boolean",
+          "default": true,
+          "description": "Auto-clear transient hints when the model uses the question tool"
+        }
+      }
+    },
+    "injection": {
+      "type": "object",
+      "description": "Controls how and where hints are injected into the model's context",
+      "additionalProperties": false,
+      "properties": {
+        "target": {
+          "type": "string",
+          "enum": ["both", "system", "user"],
+          "default": "both",
+          "description": "Where to inject hints: 'both' injects into system prompt AND user message, 'system' only into system prompt, 'user' only into user message"
+        },
+        "systemPromptPosition": {
+          "type": "string",
+          "enum": ["prepend", "append"],
+          "default": "prepend",
+          "description": "Whether to prepend or append the hint block in the system prompt"
+        },
+        "systemInstructions": {
+          "type": ["string", "null"],
+          "default": null,
+          "description": "Custom framing text for the system prompt hint block. Set to null to use the built-in default. This replaces the '## Active User Preferences' section."
+        },
+        "userMessagePrefix": {
+          "type": "string",
+          "default": "BTW, ",
+          "description": "Prefix for single-hint injection into user messages (e.g., 'BTW, ')"
+        }
+      }
+    },
+    "debug": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable debug mode by default (verbose toast logging)"
+    },
+    "toastDuration": {
+      "type": "number",
+      "default": 3000,
+      "minimum": 100,
+      "description": "Default toast notification duration in milliseconds"
+    }
+  }
+}

package.json

@@ -9,6 +9,8 @@
   "files": [
     "src/plugin.ts",
     "src/core.ts",
+    "src/config.ts",
+    "btw.schema.json",
     "LICENSE"
   ],
   "keywords": [
@@ -33,5 +35,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
   }
 }