fix: add docs

.github/workflows/release-workflow.yml

@@ -82,12 +82,13 @@ jobs:
           commit_user_name: github-actions
           commit_user_email: github-actions@github.com
           commit_author: Author <actions@github.com>
-          file_pattern: 'package.json package-lock.json'
+          file_pattern: 'package.json package-lock.json documentation/vs-code-plugin/antora.yml'
 
       - name: Create Github release
         uses: softprops/action-gh-release@de2c0eb89ae2a093876385947365aca7b0e5f844 # v0.1.15
         with:
           body: "Release version ${{ env.RELEASE_VERSION }}."
+          generate_release_notes: true
           tag_name: v${{ env.RELEASE_VERSION }}
           target_commitish: ${{ env.release_branch_name }}
           draft: false

README.md

@@ -7,6 +7,8 @@ For RDF/Turtle documents, it features syntax highlighting, document outline and
 automatic syntax validation. For SAMM Aspect Models, the extension additionally
 features *Go to Definition* for elements and semantic model validation.
 
+For installation, prerequisites, and a sample walkthrough, see the [user guide](https://eclipse-esmf.github.io/vs-code-plugin/introduction.html).
+
 ## Configuration
 
 - `semantic-models.languageServerSettings.activateEmbeddedLanguageServer` (boolean, default: `true`)
@@ -34,10 +36,13 @@ Use the command `Semantic Models: Select SAMM CLI Executable` to choose either:
 
 ## Features
 
-- Prefix `Go to Definition` inside Turtle files.
+- `Go to Definition` of referenced elements within the same file, current workspace and also for SAMM elements.
 - Two-level validation:
-  - Fast validation while typing from the regular Turtle parser diagnostics provided by the server (appear in the editor and `Problems`).
-  - Full Aspect validation from the server for model-level issues (results shown in notifications and status bar).
+  - Fast validation while typing from the regular Turtle parser.
+  - Full Aspect Model validation for model-level issues.
+- Resolve Aspect Models from a GitHub repository:
+  - Configure GitHub repositories that contain Aspect Models in extension settings.
+  - Reference elements of these Aspect Models. Features like validation and `Go to Definition` automatically fetch the model from GitHub.
 - Manual validation command:
   - `Semantic Models: Validate Document Now`
 
@@ -46,31 +51,29 @@ Use the command `Semantic Models: Select SAMM CLI Executable` to choose either:
 1. In this extension project, install the dependencies using `npm install`.
 2. Build the extension with `npm run build`.
 3. Press `F5` in VS Code to open an Extension Development Host.
-4. Open an RDF/Turtle file such as [samples/valid.ttl](samples/valid.ttl) or your Aspect model file.
+4. Open any RDF/Turtle.
 
-If the server cannot be downloaded or started, the extension shows an error and writes a detailed message in the Turtle LSP output channel.
+If the server cannot be downloaded or started, the extension shows an error and writes a detailed message in the Semantic Models output channel.
 
 ## Validation Behavior
 
 Fast feedback while typing:
 
-- Driven by the server's regular Turtle parsing diagnostics.
-- Results appear in the editor and `Problems` view.
-- Intended for quick editor feedback while you type.
+- Issues are shown immediately in the editor and Problems view.
+- Intended for quick feedback while you type.
 
 Full Aspect validation:
 
 - Runs on the server, not in the extension.
-- Results are displayed in notification messages (for manual validation) or status bar (for save-triggered validation).
+- Results appear in the editor and `Problems` view.
 - Always uses detailed server validation messaging when the server returns report text.
-- Always shows visible progress for long-running validation.
-- Runs automatically when saving and can also be triggered manually.
+- Runs automatically after a 4 second delay and when saving.
 
 When each validation runs:
 
-- On type: fast syntax feedback only.
-- On save: heavy Aspect validation for Turtle documents.
-- Manual: `Semantic Models: Validate Document Now` for the active Turtle document. User gets a summary message with validation results.
+- While typing: Turtle syntax feedback.
+- After a pause and on save: full Aspect Model validation.
+- Manual: `Semantic Models: Validate Document Now` for the active Turtle document.
 
 ## Commands
 
@@ -80,28 +83,3 @@ When each validation runs:
   - Opens a quick pick with the latest ten GitHub releases and a custom-path option.
 - `Semantic Models: Restart Language Server Connection`
   - Restarts the language server and reconnects the client.
-
-## Verify Go To Definition
-
-Use [samples/valid.ttl](samples/valid.ttl):
-
-1. Open `samples/valid.ttl`.
-2. Place the cursor on `foaf:Person`, `foaf:name`, or another prefixed name.
-3. Run `Go to Definition`.
-4. Confirm that VS Code jumps to the matching `@prefix` declaration.
-
-Expected behavior:
-
-- `foaf:*` resolves to `@prefix foaf: ...`.
-- `ex:*` resolves to `@prefix ex: ...`.
-
-## Verify Aspect Validation
-
-Use [samples/org.eclipse.esmf.test/1.0.0/Aspect.ttl](samples/org.eclipse.esmf.test/1.0.0/Aspect.ttl) or [samples/invalid.ttl](samples/invalid.ttl).
-
-Manual check:
-
-1. Open an Aspect model file.
-2. Run `Semantic Models: Validate Document Now`.
-3. Wait for validation to complete.
-4. Confirm that validation results are displayed in a notification.

documentation/vs-code-plugin/antora.yml

@@ -1,4 +1,6 @@
 name: vs-code-plugin
 title: ESMF VS Code Plugin
 version: master
-start_page: ROOT:index.adoc
+start_page: ROOT:introduction.adoc
+nav:
+  - modules/ROOT/nav.adoc

documentation/vs-code-plugin/modules/ROOT/nav.adoc

@@ -0,0 +1,7 @@
+* xref:introduction.adoc[]
+* xref:system-requirements.adoc[]
+* xref:installation.adoc[Installation]
+* xref:getting-started.adoc[]
+* xref:features.adoc[]
+* xref:support.adoc[]
+* xref:release-notes.adoc[]

documentation/vs-code-plugin/modules/ROOT/pages/features.adoc

@@ -0,0 +1,44 @@
+= Features
+
+== Editing RDF/Turtle
+
+* Syntax highlighting for `.ttl` files.
+* Document outline for navigating the current file.
+* Automatic syntax validation while typing, with diagnostics in the editor and the *Problems* view.
+
+== Working with Aspect Models
+
+* *Go to Definition* for referenced elements in the current file, workspace, and SAMM vocabulary.
+* Aspect Model validation after a pause in editing and when saving.
+* On-demand validation with *Semantic Models: Validate Document Now* from the Command Palette or editor context menu.
+
+Validation issues appear in the editor and the Problems view.
+
+[[github-model-resolution]]
+== Resolving Aspect Models from GitHub
+
+Enables *Go to Definition* and validation of Aspect Model element references stored in a GitHub repository outside the local workspace.
+
+Open *Preferences: Open User Settings (JSON)* from the Command Palette and add the repositories to `semantic-models.modelResolution.githubRepositories`.
+E.g. the following configuration enables to resolve elements from the extension samples:
+
+[source,json]
+----
+{
+	"semantic-models.modelResolution.githubRepositories": [
+		{
+			"repository": "eclipse-esmf/esmf-examples",
+			"branch": "main",
+			"path": "aspect-models"
+		}
+	]
+}
+----
+
+Set `repository` to `owner/repository` and `path` to the folder containing the models.
+To use a tag, replace `branch` with `tag`. Do not set both.
+For private repositories, add a `token` with read access in your user settings.
+Read more about how to create a GitHub Token in the https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[GitHub docs,opts=nofollow].
+
+Open a local Aspect Model that references an element in the configured repository, then use *Go to Definition* or validate the document as usual.
+The extension will automatically download the required models from GitHub.

documentation/vs-code-plugin/modules/ROOT/pages/getting-started.adoc

@@ -0,0 +1,47 @@
+= Getting Started
+
+== Opening the example workspace
+
+First, complete the xref:installation.adoc[installation and SAMM CLI setup].
+
+1. Open the https://github.com/eclipse-esmf/esmf-examples[esmf-examples repository,opts=nofollow] and choose *Code -> Download ZIP*. Extract the archive locally.
+2. In VS Code, choose *File -> Open Folder...* and open the extracted repository.
+3. Open any Aspect Model and confirm that the language mode in the status bar is *Turtle*.
+4. Wait for the language server to start. Syntax highlighting and the outline view should become available.
+
+== Validating and navigating a model
+
+1. Create an arbitrary problem, e.g., by removing the closing dot of a triple.
+2. Open *View -> Problems* and select the issue about the just removed dot.
+3. Re-add the dot.
+4. Wait for the validation to complete. The problem reported for the missing dot should disappear.
+
+Turtle syntax validation runs while typing. Aspect Model validation runs after a pause in editing and when saving.
+
+.Example of validation diagnostics
+image::walkthrough_validation.png[width=100%]
+
+If setup or validation fails, see xref:support.adoc[Support].
+
+== Creating your own workspace
+
+Create a new folder for your models and open it in VS Code.
+Models must be organized in a hierarchical manner, file paths must follow the structure: `namespace/version/name.ttl`.
+
+[source,subs=+quotes]
+----
+_models root (open folder in VS Code)_
+└── com.mycompany.myproduct
+    ├── 1.0.0
+    │   ├── MyAspect.ttl
+    │   ├── MyEntity.ttl
+    │   └── myProperty.ttl
+    └── 1.1.0
+        └── MyAspect.ttl
+----
+
+The namespace and version directories must match the namespace and version in the model URNs.
+For example, files in `com.mycompany.myproduct/1.0.0` use `@prefix : <urn:samm:com.mycompany.myproduct:1.0.0#> .`.
+
+Read more about xref:esmf-developer-guide:tooling-guide:samm-cli.adoc#models-directory-structure[models directory structure,opts=nofollow]
+and xref:esmf-developer-guide:tooling-guide:java-aspect-tooling.adoc#understanding-model-resolution[model resolution,opts=nofollow].

documentation/vs-code-plugin/modules/ROOT/pages/installation.adoc

@@ -0,0 +1,24 @@
+= Install the Semantic Models for VS Code Extension
+
+First, check the xref:system-requirements.adoc[system requirements].
+
+== Installing the extension
+
+Open the *Extensions* view in VS Code, search for *Semantic Models* published by *eclipse-esmf*, and select *Install*.
+You can also open https://marketplace.visualstudio.com/items?itemName=eclipse-esmf.semantic-models[Semantic Models on Visual Studio Marketplace,window=_blank,opts=nofollow].
+
+For a manual installation, download the latest `.vsix` file from the https://github.com/eclipse-esmf/esmf-vs-code-plugin/releases[extension releases,opts=nofollow].
+In VS Code, open *View -> Command Palette*, run *Extensions: Install from VSIX...*, and select the downloaded file.
+
+== Configuration
+
+After successful extension installation, a welcome screen should greet you:
+
+image::walkthrough_welcome.png[width=100%]
+
+Follow the instructions on the welcome screen to configure the extension.
+
+If the welcome screen does not open, you need to manually configure the extension. Open *View -> Command Palette*, run *Semantic Models: Select SAMM CLI Executable*.
+Configuring this executable is necessary for the extension to work properly.
+
+If setup or validation fails, see xref:support.adoc[Support].

documentation/vs-code-plugin/modules/ROOT/pages/introduction.adoc

@@ -0,0 +1,16 @@
+= Introduction
+
+Semantic Models for VS Code is a Visual Studio Code extension for editing RDF/Turtle documents,
+including xref:samm-specification:ROOT:index.adoc[SAMM Aspect Models,opts=nofollow] of the
+xref:esmf-documentation:ROOT:index.adoc[Eclipse Semantic Modeling Framework (ESMF),opts=nofollow].
+
+For RDF/Turtle documents, it features syntax highlighting, document outline and automatic syntax validation.
+For SAMM Aspect Models, the extension additionally features *Go to Definition* for elements and semantic model validation.
+
+image::walkthrough_validation.png[width=100%]
+
+== Comparison with the Aspect Model Editor
+
+The xref:ame-guide:ROOT:introduction.adoc[Aspect Model Editor,opts=nofollow] provides graphical editing of Aspect Models.
+The Semantic Models extension provides direct Turtle editing within VS Code, alongside its search, navigation and Git tools. 
+This is ideal for users like software developers who are familiar with SAMM, RDF/Turtle and VS Code.

documentation/vs-code-plugin/modules/ROOT/pages/release-notes.adoc

@@ -0,0 +1,3 @@
+= Release Notes
+
+Find the release notes for the Semantic Models extension at the https://github.com/eclipse-esmf/esmf-vs-code-plugin/releases[GitHub releases overview^,opts=nofollow].

documentation/vs-code-plugin/modules/ROOT/pages/support.adoc

@@ -0,0 +1,57 @@
+= Support
+
+For troubleshooting, see the <<known-issues,known issues>> below.
+Also make sure your system meets the xref:system-requirements.adoc[system requirements].
+
+As the Semantic Models extension relies on the SAMM specification, also check out the xref:samm-specification:ROOT:index.adoc[SAMM Aspect Meta Model,opts=nofollow].
+
+For further support, open an https://github.com/eclipse-esmf/esmf-vs-code-plugin/issues[issue in GitHub^,opts=nofollow].
+Include the following in your issue:
+
+* Steps to reproduce the issue.
+* Expected behavior.
+* Actual behavior.
+* Operating system, VS Code version, extension version, and SAMM CLI version.
+* Relevant screenshots, minimal Turtle files, and logs. Remove tokens and other sensitive data.
+
+[[known-issues]]
+== Known issues
+
+[[selection-and-download-of-samm-cli-fails]]
+=== SAMM CLI selection or download fails
+
+One possible cause is a GitHub API rate limit. Check the *Semantic Models* output channel for the reported error.
+If the release picker or download fails, try selecting a manually downloaded CLI:
+
+1. Go to the https://github.com/eclipse-esmf/esmf-sdk/releases[ESMF SDK releases page^,opts=nofollow] and manually download the SAMM CLI for your platform from the latest release. 
+2. Extract the archive if necessary and move the cli to a suitable location for permanent storage.
+3. Run *Semantic Models: Select SAMM CLI Executable* from the Command Palette. 
+4. Choose `Use custom SAMM CLI executable or jar file`, and select the downloaded executable or JAR file.
+
+[[language-server-stops-being-available]]
+=== Language server stops being available
+
+If language features such as syntax highlighting are unavailable, it may be due to the language server not running.
+To start or restart it manually, open the Command Palette (View -> Command Palette) and run `Semantic Models: Restart Language Server Connection`.
+
+
+== Accessing the VS Code extension logs (for troubleshooting/debugging)
+
+To facilitate your troubleshooting efforts or when you need to compile detailed information for a GitHub issue, VS Code enables access to extension logs.
+
+*Opening extension logs*
+
+Open *View -> Output*. Select Semantic Models in the output dropdown menu.
+
+*Enabling detailed logging*
+
+The default logging level in VS Code is `info`. This might not be enough to understand the cause of certain issues.
+In order to get a more complete picture, increase the logging level to `debug`.
+Open *View -> Command Palette* and run *Developer: Set Log Level...*.
+This allows you to configure the logging level either globally or on a per extension basis.
+Select the Semantic Models extension and re-configure the logging level to e.g. `debug`.
+
+{nbsp}
+
+For general questions on semantic data structuring and the role of the Semantic Models extension, join the
+https://chat.eclipse.org/#/room/#eclipse-semantic-modeling-framework:matrix.eclipse.org[ESMF Chat^,opts=nofollow].

documentation/vs-code-plugin/modules/ROOT/pages/system-requirements.adoc

@@ -0,0 +1,9 @@
+= System Requirements
+
+* Visual Studio Code 1.110.0 or later, with permission to install extensions.
+* Windows, macOS, or Linux, with a SAMM CLI distribution compatible with your operating system and CPU architecture. Check the https://github.com/eclipse-esmf/esmf-sdk/releases[SAMM CLI releases,opts=nofollow].
+
+== Network Access
+
+Internet access is required to download the extension and SAMM CLI, check for updates, and resolve models from GitHub.
+The language server uses a local TCP connection on port `1846` by default.