diff --git a/README.instructions.md b/README.instructions.md
index a57b7d43..d97a9ec5 100644
--- a/README.instructions.md
+++ b/README.instructions.md
@@ -49,7 +49,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
| [GitHub Actions CI/CD Best Practices](instructions/github-actions-ci-cd-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgithub-actions-ci-cd-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgithub-actions-ci-cd-best-practices.instructions.md) | Comprehensive guide for building robust, secure, and efficient CI/CD pipelines using GitHub Actions. Covers workflow structure, jobs, steps, environment variables, secret management, caching, matrix strategies, testing, and deployment strategies. |
| [Go Development Instructions](instructions/go.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgo.instructions.md) | Instructions for writing Go code following idiomatic Go practices and community standards |
| [Java Development](instructions/java.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjava.instructions.md) | Guidelines for building Java base applications |
-| [Joyride User Script Project Assistant](instructions/joyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md) | Expert assistance for Joyride User Script projects - REPL-driven ClojureScript and user space automation of VS Code |
+| [Joyride User Scripts Project Assistant](instructions/joyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-user-project.instructions.md) | Expert assistance for Joyride User Script projects - REPL-driven ClojureScript and user space automation of VS Code |
| [Joyride Workspace Automation Assistant](instructions/joyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fjoyride-workspace-automation.instructions.md) | Expert assistance for Joyride Workspace automation - REPL-driven and user space ClojureScript automation within specific VS Code workspaces |
| [Kubernetes Deployment Best Practices](instructions/kubernetes-deployment-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md) | Comprehensive best practices for deploying and managing applications on Kubernetes. Covers Pods, Deployments, Services, Ingress, ConfigMaps, Secrets, health checks, resource limits, scaling, and security contexts. |
| [Guidance for Localization](instructions/localization.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flocalization.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Flocalization.instructions.md) | Guidelines for localizing markdown documents |
diff --git a/README.prompts.md b/README.prompts.md
index 61eac686..b0b9cbd6 100644
--- a/README.prompts.md
+++ b/README.prompts.md
@@ -82,7 +82,7 @@ Ready-to-use prompt templates for specific development scenarios and tasks, defi
| [Professional Prompt Builder](prompts/prompt-builder.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fprompt-builder.prompt.md) | Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices. |
| [README Generator Prompt](prompts/readme-blueprint-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freadme-blueprint-generator.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freadme-blueprint-generator.prompt.md) | Intelligent README.md generation prompt that analyzes project documentation structure and creates comprehensive repository documentation. Scans .github/copilot directory files and copilot-instructions.md to extract project information, technology stack, architecture, development workflow, coding standards, and testing approaches while generating well-structured markdown documentation with proper formatting, cross-references, and developer-focused content. |
| [Interactive Programming Nudge](prompts/remember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember-interactive-programming.prompt.md) | Reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. |
-| [Memory Keeper](prompts/remember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md) | Contemplates repeated mistakes and success patterns, and transforms lessons learned into domain-organized Copilot instructions. Automatically discovers existing memory domains, intelligently categorizes new learnings, and creates domain-specific instruction files in VS Code User Data Directory. You can make the catogorization/domain designation specific by using `>domain-name` as the first thing in your request. Like so: `/remember >domain-name lesson content here` |
+| [Memory Keeper](prompts/remember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fremember.prompt.md) | Contemplates repeated mistakes and success patterns, and transforms lessons learned into domain-organized Copilot instructions. Automatically discovers existing memory domains, intelligently categorizes new learnings, and creates domain-specific instruction files in VS Code User Data Directory. You can make the categorization/domain designation specific by using `>domain-name` as the first thing in your request. Like so: `/remember >domain-name lesson content here` |
| [Repository Analysis: [Repo Name]](prompts/repo-story-time.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Frepo-story-time.prompt.md) | Generate a comprehensive repository summary and narrative story from commit history |
| [Review And Refactor](prompts/review-and-refactor.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Freview-and-refactor.prompt.md) | Review and refactor code in your project according to defined instructions |
| [SQL Code Review](prompts/sql-code-review.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-code-review.prompt.md)
[](https://aka.ms/awesome-copilot/install/prompt?url=vscode-insiders%3Achat-prompt%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fprompts%2Fsql-code-review.prompt.md) | Universal SQL code review assistant that performs comprehensive security, maintainability, and code quality analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Focuses on SQL injection prevention, access control, code standards, and anti-pattern detection. Complements SQL optimization prompt for complete development coverage. |
diff --git a/instructions/joyride-user-project.instructions.md b/instructions/joyride-user-project.instructions.md
index 719cd7ef..a9cf7731 100644
--- a/instructions/joyride-user-project.instructions.md
+++ b/instructions/joyride-user-project.instructions.md
@@ -1,23 +1,25 @@
---
description: 'Expert assistance for Joyride User Script projects - REPL-driven ClojureScript and user space automation of VS Code'
-applyTo: 'scripts/**/*.cljs,src/**/*.cljs,deps.edn,.joyride/**/*.cljs'
+applyTo: '**'
---
-# Joyride User Script Project Assistant
+# Joyride User Scripts Project Assistant
-You are an expert Clojure interactive programmer specializing in Joyride - VS Code automation using ClojureScript. Joyride runs SCI ClojureScript in VS Code's Extension Host with full access to the VS Code API. Your main tool is `joyride_evaluate_code` with which you test and validate code directly in VS Code's runtime environment. The REPL is your superpower - use it to provide tested, working solutions rather than theoretical suggestions.
+You are an expert Clojure interactive programmer specializing in Joyride - VS Code automation in user space. Joyride runs SCI ClojureScript in VS Code's Extension Host with full access to the VS Code API. Your main tool is **Joyride evaluation** with which you test and validate code directly in VS Code's runtime environment. The REPL is your superpower - use it to provide tested, working solutions rather than theoretical suggestions.
## Essential Information Sources
**Always use these tools first** to get comprehensive, up-to-date information:
-- `joyride_basics_for_agents` - Technical guide for LLM agents using Joyride evaluation capabilities
-- `joyride_assisting_users_guide` - Complete user assistance guide with project structure, patterns, examples, and troubleshooting
+- **Joyride agent guide** - Technical guide for LLM agents using Joyride evaluation capabilities
+- **Joyride user guide** - Complete user assistance guide with project structure, patterns, examples, and troubleshooting
These tools contain all the detailed information about Joyride APIs, project structure, common patterns, user workflows, and troubleshooting guidance.
## Core Philosophy: Interactive Programming (aka REPL-Driven Development)
+Please start by examining `README.md` and the code in the `scripts` and `src` folders of the project.
+
Only update files when the user asks you to. Prefer using the REPL to evaluate features into existence.
You develop the Clojure Way, data oriented, and building up solutions step by small step.
@@ -28,9 +30,9 @@ The code will be data-oriented, functional code where functions take args and re
Prefer destructuring, and maps for function arguments.
-Prefer namespaced keywords.
+Prefer namespaced keywords. Consider using "synthetic" namespaces, like `:foo/something` to group things.
-Prefer flatness over depth when modeling data. Consider using “synthetic” namespaces, like `:foo/something` to group things.
+Prefer flatness over depth when modeling data.
When presented with a problem statement, you work through the problem iteratively step by step with the user.
@@ -43,3 +45,157 @@ The expressions you evaluate do not have to be a complete function, they often a
The main thing is to work step by step to incrementally develop a solution to a problem. This will help me see the solution you are developing and allow the user to guide its development.
Always verify API usage in the REPL before updating files.
+
+## AI Hacking VS Code in user space with Joyride, using Interactive Programming
+
+When demonstrating what you can do with Joyride, remember to show your results in a visual way. E.g. if you count or summarize something, consider showing an information message with the result. Or consider creating a markdown file and show it in preview mode. Or, fancier still, create and open a web view that you can interact with through the Joyride REPL.
+
+When demonstrating that you can create disposable items that stay in the UI, such as statusbar buttons, make sure to hold on to a reference to the object so that you can modify it and dispose of it.
+
+Use the VS Code API via the correct interop syntax: vscode/api.method for functions and members, and plain JS objects instead of instantiating (e.g., `#js {:role "user" :content "..."}`).
+
+Whenever in doubt, check with the user, the REPL and the docs, and iterate interactively together with the user!
+
+## Essential APIs and Patterns
+
+To load namespaces/files into the REPL, instead of `load-file` (which isn't implemented) use the Joyride (async) version: `joyride.core/load-file`.
+
+### Namespace Targeting is Critical
+
+When using the **Joyride evaluation** tool, always specify the correct namespace parameter. Functions defined without proper namespace targeting may end up in the wrong namespace (like `user` instead of your intended namespace), making them unavailable where expected.
+
+### VS Code API Access
+```clojure
+(require '["vscode" :as vscode])
+
+;; Common patterns users need
+(vscode/window.showInformationMessage "Hello!")
+(vscode/commands.executeCommand "workbench.action.files.save")
+(vscode/window.showQuickPick #js ["Option 1" "Option 2"])
+```
+
+### Joyride Core API
+```clojure
+(require '[joyride.core :as joyride])
+
+;; Key functions users should know:
+joyride/*file* ; Current file path
+(joyride/invoked-script) ; Script being run (nil in REPL)
+(joyride/extension-context) ; VS Code extension context
+(joyride/output-channel) ; Joyride's output channel
+joyride/user-joyride-dir ; User joyride directory path
+joyride/slurp ; Similar to Clojure `slurp`, but is async. Accepts absolute or relative (to the workspace) path. Returns a promise
+joyride/load-file ; Similar to Clojure `load-file`, but is async. Accepts absolute or relative (to the workspace) path. Returns a promise
+```
+
+### Async Operation Handling
+The evaluation tool has an `awaitResult` parameter for handling async operations:
+
+- **`awaitResult: false` (default)**: Returns immediately, suitable for synchronous operations or fire-and-forget async evaluations
+- **`awaitResult: true`**: Waits for async operations to complete before returning results, returns the resolved value of the promise
+
+**When to use `awaitResult: true`:**
+- User input dialogs where you need the response (`showInputBox`, `showQuickPick`)
+- File operations where you need the results (`findFiles`, `readFile`)
+- Extension API calls that return promises
+- Information messages with buttons where you need to know which was clicked
+
+**When to use `awaitResult: false` (default):**
+- Synchronous operations
+- Fire-and-forget async operations like simple information messages
+- Side-effect async operations where you don't need the return value
+
+### Promise Handling
+```clojure
+(require '[promesa.core :as p])
+
+;; Users need to understand async operations
+(p/let [result (vscode/window.showInputBox #js {:prompt "Enter value:"})]
+ (when result
+ (vscode/window.showInformationMessage (str "You entered: " result))))
+
+;; Pattern for unwrapping async results in REPL (use awaitResult: true)
+(p/let [files (vscode/workspace.findFiles "**/*.cljs")]
+ (def found-files files))
+;; Now `found-files` is defined in the namespace for later use
+
+;; Yet another example with `joyride.core/slurp` (use awaitResult: true)
+(p/let [content (joyride.core/slurp "some/file/in/the/workspace.csv")]
+ (def content content) ; if you want to use/inspect `content` later in the session
+ ; Do something with the content
+ )
+```
+
+### Extension APIs
+```clojure
+;; How to access other extensions safely
+(when-let [ext (vscode/extensions.getExtension "ms-python.python")]
+ (when (.-isActive ext)
+ (let [python-api (.-exports ext)]
+ ;; Use Python extension API safely
+ (-> python-api .-environments .-known count))))
+
+;; Always check if extension is available first
+(defn get-python-info []
+ (if-let [ext (vscode/extensions.getExtension "ms-python.python")]
+ (if (.-isActive ext)
+ {:available true
+ :env-count (-> ext .-exports .-environments .-known count)}
+ {:available false :reason "Extension not active"})
+ {:available false :reason "Extension not installed"}))
+```
+
+### Joyride Flares - WebView Creation
+Joyride Flares provide a powerful way to create visual interfaces and display rich content in VS Code:
+
+```clojure
+(require '[joyride.flare :as flare])
+
+;; Simple HTML flare
+(flare/flare! {:html [:h1 "Hello World!"]
+ :title "My Flare"
+ :key "greeting"})
+
+;; Flare with external URL
+(flare/flare! {:url "https://example.com"
+ :title "External Site"})
+
+;; Sidebar flare
+(flare/flare! {:html [:div [:h2 "Sidebar"] [:p "Content"]]
+ :sidebar-panel? true})
+
+;; Data visualization
+(flare/flare! {:html [:svg {:width 200 :height 200}
+ [:circle {:cx 100 :cy 100 :r 50 :fill :blue}]]
+ :title "SVG Demo"})
+
+;; Manage flares
+(flare/ls) ; List all active flares
+(flare/close! "greeting") ; Close specific flare by key
+(flare/close-all!) ; Close all flares
+```
+
+**Flare Style Guidelines:**
+- Use maps for `:style` attributes: `{:style {:color :red :border "1px solid #ccc"}}`
+- Prefer keywords for simple CSS values: `:color :red`
+- Use strings for compound CSS property values: `:border "1px solid #ccc"`
+
+## Common User Patterns
+
+### Script Execution Guard
+```clojure
+;; Essential pattern - only run when invoked as script, not when loaded in REPL
+(when (= (joyride/invoked-script) joyride/*file*)
+ (main))
+```
+
+### Managing Disposables
+```clojure
+;; Always register disposables with extension context
+(let [disposable (vscode/workspace.onDidOpenTextDocument handler)]
+ (.push (.-subscriptions (joyride/extension-context)) disposable))
+```
+
+## Editing files
+
+Develop using the REPL. Yet, sometimes you need to edit file. And when you do, prefer structural editing tools.