Polish plugin toward first-class IntelliJ integration

.github/workflows/build.yml

@@ -1,9 +1,7 @@
 # GitHub Actions Workflow created for testing and preparing the plugin release in following steps:
-# - validate Gradle Wrapper,
+# - validate the Gradle wrapper,
 # - run 'test' and 'verifyPlugin' tasks,
-# - run Qodana inspections,
 # - run 'buildPlugin' task and prepare artifact for the further tests,
-# - run 'runPluginVerifier' task,
 # - create a draft release.
 #
 # Workflow is triggered on push and pull_request events.
@@ -31,6 +29,8 @@ jobs:
     steps:
       - name: Fetch Sources
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: Validate Gradle Wrapper
+        uses: gradle/actions/wrapper-validation@48b5f213c81028ace310571dc5ec0fbbca0b2947 # v4
       - name: Setup Java
         uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4
         with:
@@ -78,14 +78,15 @@ jobs:
           VERSION="$(echo "$PROPERTIES" | grep "^version:" | cut -f2- -d ' ')"
           NAME="$(echo "$PROPERTIES" | grep "^pluginName:" | cut -f2- -d ' ')"
           CHANGELOG="$(./gradlew getChangelog --no-header --console=plain -q)"
-          CHANGELOG="${CHANGELOG//'%'/'%25'}"
-          CHANGELOG="${CHANGELOG//$'\n'/'%0A'}"
-          CHANGELOG="${CHANGELOG//$'\r'/'%0D'}"
 
-          echo "::set-output name=version::$VERSION"
-          echo "::set-output name=name::$NAME"
-          echo "::set-output name=changelog::$CHANGELOG"
-          echo "::set-output name=pluginVerifierHomeDir::~/.pluginVerifier"
+          {
+            echo "version=$VERSION"
+            echo "name=$NAME"
+            echo "pluginVerifierHomeDir=~/.pluginVerifier"
+            echo "changelog<<CHANGELOG_EOF"
+            echo "$CHANGELOG"
+            echo "CHANGELOG_EOF"
+          } >> "$GITHUB_OUTPUT"
 
           ./gradlew printProductsReleases # prepare list of IDEs for Plugin Verifier
 
@@ -120,7 +121,7 @@ jobs:
           FILENAME=`ls *.zip`
           unzip "$FILENAME" -d content
 
-          echo "::set-output name=filename::$FILENAME"
+          echo "filename=$FILENAME" >> "$GITHUB_OUTPUT"
 
       # Store already-built plugin as an artifact for downloading
       - name: Upload artifact

.gitignore

@@ -150,3 +150,6 @@ gradle-app.setting
 
 !src/main/libs/jbang.jar
 bin
+
+# macOS metadata
+.DS_Store

CHANGELOG.md

@@ -4,12 +4,38 @@
 
 ## [Unreleased]
 
+### Added
+- The New JBang Script dialog now has a Copy button beside the generated `jbang init`
+  command preview.
+- Directive-argument completion for `//JAVA` versions, `//REPOS` shortcuts, and `//MAIN`
+  classes, plus multi-value completion for additional `//DEPS`, `//SOURCES`, and `//FILES`
+  entries on the same directive.
+- Quick fixes to uppercase a mis-cased directive and to remove a duplicate `//DEPS` entry.
+- JShell (`.jsh`) scripts now receive directive and directive-argument completion.
+- Settings now link to the documentation and issue tracker.
+- Troubleshooting, known-limitations, and architecture documentation pages, plus a
+  `CONTRIBUTING.md`.
+
+### Changed
+- New Script creation validates the destination and no longer overwrites files silently:
+  existing files, absolute paths, and paths escaping the selected directory are rejected,
+  while nested destinations are created and opened.
+- Run/Debug configurations created from context are matched by script path (not just name)
+  and created as temporary configurations, so same-named scripts in different directories no
+  longer collide.
+- Script detection now only recognises directives in the initial comment block at column
+  zero, matching JBang, and consistently scans the first 200 lines.
+- The catalog JSON schema accepts current Java versions and template properties.
+- Feature tips link to the published documentation instead of GitHub source.
+
 ### Fixed
 - JBang auto-detection now uses IntelliJ's console/shell environment PATH before
   the IDE process PATH, so installs from tools such as SDKMAN are found when
   IntelliJ was launched outside that shell.
 - Persisted JBang settings now read and write the loaded state correctly after
   IDE restart.
+- Run configurations validate the script, working directory, and JBang availability before
+  launching.
 
 ## [0.101.0]
 

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to the JBang IntelliJ plugin
+
+Thanks for helping improve the plugin. This project follows a strict test-first
+workflow.
+
+## Test-first workflow
+
+Every behavioral change starts with a failing test:
+
+1. Write a test that reproduces the bug or specifies the feature.
+2. Run it and confirm it fails.
+3. Implement the smallest change that makes it pass.
+4. Run the targeted test, then the full suite.
+5. Update `CHANGELOG.md` under `[Unreleased]` for any user-visible change.
+
+Every user-facing feature must have at least one test that verifies the
+user-visible contract (gutter icon, action registration, completion results,
+run configuration discovery), not only an internal method.
+
+## Build and test
+
+```sh
+./gradlew test                                   # run all tests
+./gradlew test --tests "dev.jbang.idea.run.*"    # run specific tests
+./gradlew runIde                                 # launch a sandbox IDE
+./gradlew buildPlugin                            # build the distributable zip
+./gradlew verifyPlugin --args='-mute TemplateWordInPluginId'  # compatibility check
+```
+
+Building the plugin requires JDK 25. The plugin targets IntelliJ IDEA 2026.2+.
+
+## IntelliJ platform conventions
+
+- Override `getOptionsClass()` on run configurations.
+- Register a `ProgramRunner` for every supported executor ID.
+- `AdditionalLibraryRootsListener.fireAdditionalLibraryChanged()` needs write
+  access on EDT.
+- Call terminal-widget operations on the correct thread (`createNewSession` on
+  EDT, `hasRunningCommands` off EDT).
+- Handle both `PsiComment` and `PsiDocComment` when walking JBang files, because
+  the shebang parses as Javadoc.
+
+See [AGENTS.md](AGENTS.md) for the full set of conventions and architecture
+notes, and [docs](docs/modules/ROOT/pages/architecture.adoc) for the
+integration model.
+
+## Documentation
+
+User-visible changes must update the AsciiDoc pages under
+`docs/modules/ROOT/pages/` and any relevant screenshots.

README.md

@@ -44,7 +44,7 @@ No project wizard or module setup required — just open a folder.
 Version 0.100.0 is a ground-up rewrite of the plugin. The old plugin (≤ 0.26) mutated IntelliJ modules, mirrored dependencies into Gradle, and used a custom tool window. The new plugin:
 
 * Uses `jbang info tools` as the single source of truth — no module mutation, no Gradle mirroring
-* Overlays dependencies as synthetic libraries — existing Gradle/Maven projects are never touched
+* Overlays dependencies as synthetic libraries — existing Gradle/Maven projects keep their own model (see [Architecture](docs/modules/ROOT/pages/architecture.adoc) for the one narrow Kotlin K2 exception)
 * Supports multiple root scripts with isolated classpaths and JDKs
 * Adds Debug support, terminal execution, WSL support, and detailed diagnostics
 * Replaces the tool window with a status bar widget and External Libraries integration
@@ -81,7 +81,7 @@ Install it via <kbd>Settings</kbd> > <kbd>Plugins</kbd> > <kbd>⚙</kbd> > <kbd>
 
 ## Contributing
 
-See [AGENTS.md](AGENTS.md) for test-first workflow, IntelliJ platform conventions, and architecture notes.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the test-first workflow, IntelliJ platform conventions, and architecture notes.
 
 ```sh
 ./gradlew test                              # run all tests