Add Usage spec export command

build.gradle

@@ -19,7 +19,6 @@ plugins {
 	id 'maven-publish'
 	id 'io.qameta.allure-report' version '2.12.0'
 	id "io.qameta.allure-adapter-base" version "2.12.0"
-
 }
 
 def allureVersion = '2.29.1'
@@ -160,7 +159,7 @@ dependencies {
 	annotationProcessor 'info.picocli:picocli-codegen:4.7.7'
 	implementation 'io.quarkus.qute:qute-core:1.13.7.Final'
 	implementation 'org.codehaus.plexus:plexus-java:1.2.0'
-	implementation 'com.google.code.gson:gson:2.10.1'
+	implementation 'com.google.code.gson:gson:2.13.2'
 	implementation 'org.jsoup:jsoup:1.17.1'
 	implementation 'org.codejive:java-properties:0.0.7'
 

docs/modules/ROOT/pages/alias_catalogs.adoc

@@ -15,6 +15,8 @@ endif::[]
 To avoid remembering long paths and to enable easy launch of jbang scripts there is an `alias` command
 to setup and manage aliases to actual scripts.
 
+NOTE: If your goal is to publish app commands for others, start with xref:publishing-app-catalogs.adoc[Publishing App Catalogs]. It is a shorter, app-focused guide for enabling commands like `jbang <cmd>@<your-org>`.
+
 [source,bash]
 ----
 jbang alias add --name hello https://github.com/jbangdev/jbang-examples/blob/HEAD/examples/helloworld.java

docs/modules/ROOT/pages/app-installation.adoc

@@ -311,6 +311,7 @@ ls -la ~/.jbang/bin/
 
 == What's Next?
 
+- **Publish your apps via catalogs** → xref:publishing-app-catalogs.adoc[Publishing App Catalogs]
 - **Share your tools** → xref:alias_catalogs.adoc[Aliases & Catalogs]
 - **Build complex apps** → xref:organizing.adoc[Organizing Code]
 - **Create native binaries** → xref:native-images.adoc[Native Images]

docs/modules/ROOT/pages/index.adoc

@@ -80,6 +80,7 @@ Explore powerful JBang capabilities:
 * xref:running.adoc[Running & Execution] - Advanced execution options
 * xref:editing.adoc[IDE Integration] - Edit with full IDE support
 * xref:exporting.adoc[Exporting Projects] - Convert to traditional projects
+* xref:publishing-app-catalogs.adoc[Publishing App Catalogs] - Let users run your tools as `jbang <cmd>@<your-org>`
 * xref:alias_catalogs.adoc[Aliases & Catalogs] - Share and manage scripts
 
 === ⚙️ Configuration & Tools

docs/modules/ROOT/pages/locking.adoc

@@ -0,0 +1,62 @@
+= Locking & Checksum Verification
+
+JBang supports lightweight integrity and reproducibility checks via digests and lock files.
+
+== Verify a single ref
+
+Use an inline digest suffix:
+
+[source,bash]
+----
+jbang run env@jbangdev#sha256:35a0c5c82720
+----
+
+You can also pass `--verify` explicitly:
+
+[source,bash]
+----
+jbang run --verify sha256:35a0c5c82720 env@jbangdev
+----
+
+NOTE: Digest prefixes are supported (minimum 12 hex chars).
+
+== Generate lock entries
+
+Create/update `.jbang.lock` for a ref:
+
+[source,bash]
+----
+jbang lock env@jbangdev
+jbang lock dev.tamboui:tamboui-toolkit:0.1.0
+----
+
+By default JBang stores:
+
+- `ref=sha256:...` (root digest)
+- `ref.sources=...` (resolved sources, when applicable)
+- `ref.deps=...` (resolved transitive dependency coordinates, when applicable)
+
+== Enforce lock checks
+
+Run in strict locked mode:
+
+[source,bash]
+----
+jbang --locked env@jbangdev
+jbang --locked dev.tamboui:tamboui-toolkit:0.1.0
+----
+
+Locked mode validates:
+
+- root digest
+- source manifest (if present)
+- dependency graph (if present)
+
+If any drift is detected, JBang fails with a clear mismatch error.
+
+== Use another lock file
+
+[source,bash]
+----
+jbang --lock-file /path/to/my.lock --locked env@jbangdev
+----

docs/modules/ROOT/pages/publishing-app-catalogs.adoc

@@ -0,0 +1,173 @@
+= Publish Apps with a JBang Catalog
+:idprefix:
+:idseparator: -
+ifndef::env-github[]
+:icons: font
+endif::[]
+ifdef::env-github[]
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+
+If you follow this guide, users can run your tools like this:
+
+[source,bash]
+----
+jbang <cmd>@<your-org>
+
+jbang mytool@your-org     
+jbang mytool-lts@your-org
+----
+
+Once you have such a name for you app, users can run it via jbang - but can also install it as a command on their system, using `jbang app install <cmd>@<your-org>`.
+
+[source,bash]
+----
+jbang app install mytool@your-org
+mytool --help
+----
+
+Real-world examples of commands you can run:
+
+[source,bash]
+---
+jbang minecraft-server@microsoft
+jbang camel@redhat-camel
+jbang quarkus@quarkusio
+jbang arthas@alibaba
+----
+
+That is the main value of a catalog: your users get a short, stable command name, and JBang handles how to run the app behind it.
+
+
+For most teams publishing apps, the best starting point is aliases that target released Maven artifacts (GAVs) or JARs. JBang scripts are also supported, but
+not a requirement.
+
+== Why publish a catalog?
+
+A catalog gives you:
+
+- A simple command UX (`<cmd>@<your-org>`) for your users
+- One place to curate and describe your app commands
+- Flexibility to point commands at Maven coordinates, JARs, or scripts without changing user-facing command names
+
+In other words, you publish app names; JBang handles execution details.
+
+== What should aliases point to?
+
+For app catalogs, this is the recommended order:
+
+1. **Maven artifact (GAV)** - best default for versioned releases
+2. **JAR** - great for private/internal distribution or direct downloads, i.e. github releases
+3. **Script** - fully supported, but usually a secondary publishing path for app catalogs
+
+JBang treats all of these as runnable app targets behind the same alias UX.
+
+== Where should the catalog live?
+
+[cols="1,2,2,2", options="header"]
+|===
+|Option |Where to put it |How users run it |Best for
+
+|**Org-level catalog** (recommended)
+|Create a repository named `jbang-catalog` under your org/user
+|`jbang <cmd>@<your-org>`
+|Multiple tools and a stable, shorter, org-wide command namespace
+
+|**Repo-level catalog**
+|Add `jbang-catalog.json` to an existing repository
+|`jbang <cmd>@<your-org>/<repo>`
+|A single product/repository that owns its own commands, and no org-wide command namespace
+|===
+
+== Option A: org-level catalog repository (recommended)
+
+[TIP]
+====
+Run `jbang init -t jbang-catalog jbang-catalog` to quickly create a catalog repository with renovatebot and GitHub action setup to keep dependencies up to date. Then you can skip to step #3
+====
+
+=== 1) Create the catalog repository
+
+Create `https://github.com/<your-org>/jbang-catalog` (or equivalent on GitLab/Bitbucket).
+
+=== 2) Add `jbang-catalog.json`
+
+Use a minimal app-focused catalog like this:
+
+[source,json]
+----
+{
+  "aliases": {
+    "mytool": {
+      "script-ref": "com.yourorg:mytool-cli:1.3.0",
+      "description": "Run MyTool CLI from Maven"
+    },
+    "mytool-lts": {
+      "script-ref": "https://downloads.yourorg.com/mytool/mytool-cli-1.2.5.jar",
+      "description": "Run MyTool LTS jar"
+    }
+  }
+}
+----
+
+`script-ref` is the target field name and can point to a GAV, JAR, or script. For app catalogs, prefer GAV or JAR targets first.
+
+=== 3) Commit and push
+
+Publish the file in the default branch.
+
+=== 4) Validate the user command
+
+[source,bash]
+----
+jbang mytool@your-org
+----
+
+If needed while iterating on changes, test with `--fresh` to bypass caches.
+
+== Option B: catalog file in an existing repository
+
+If you do not want a dedicated `jbang-catalog` repository, add `jbang-catalog.json` to your existing repository.
+
+With a file in the repo root, users can run:
+
+[source,bash]
+----
+jbang mytool@your-org/your-repo
+----
+
+This is often a good fit when command aliases are tightly coupled to one project.
+
+== Managing entries quickly
+
+Instead of editing JSON by hand, you can add aliases via CLI:
+
+[source,bash]
+----
+# Preferred: alias pointing to Maven artifact (GAV)
+jbang alias add --file jbang-catalog.json --name mytool \
+  --description "Run MyTool CLI from Maven" \
+  com.yourorg:mytool-cli:1.3.0
+
+# Preferred: alias pointing to JAR
+jbang alias add --file jbang-catalog.json --name mytool-lts \
+  --description "Run MyTool LTS jar" \
+  https://downloads.yourorg.com/mytool/mytool-cli-1.2.5.jar
+
+# Also supported: alias pointing to script
+jbang alias add --file jbang-catalog.json --name mytool-dev \
+  --description "Run MyTool development script" \
+  mytool.java
+----
+
+See the full reference for xref:jbang:cli:jbang-alias.adoc[`jbang alias`] and xref:jbang:cli:jbang-catalog.adoc[`jbang catalog`].
+
+== Beyond app commands (optional)
+
+Catalogs can also include templates and other entries (for example, jshell-oriented helpers), but most teams should start by publishing clear app aliases first.
+
+For advanced catalog behavior and implicit catalog syntax details, see xref:alias_catalogs.adoc[Aliases & Catalogs] and xref:templates.adoc[Templates].

docs/modules/ROOT/partials/nav.adoc

@@ -15,6 +15,7 @@
 
 * Running & Execution
 ** xref:jbang:ROOT:execution-options.adoc[Execution Options]
+** xref:jbang:ROOT:locking.adoc[Locking & Checksums]
 ** xref:jbang:ROOT:remote-execution.adoc[Remote Execution]
 ** xref:jbang:ROOT:native-images.adoc[Native Images]
 ** xref:jbang:ROOT:self-contained-executables.adoc[Self-Contained Executables]
@@ -23,6 +24,7 @@
 * Distribution & Deployment
 ** xref:jbang:ROOT:exporting.adoc[Exporting Projects]
 ** xref:jbang:ROOT:app-installation.adoc[Installing as Apps]
+** xref:jbang:ROOT:publishing-app-catalogs.adoc[Publishing App Catalogs]
 ** xref:jbang:ROOT:alias_catalogs.adoc[Aliases & Catalogs]
 ** xref:jbang:ROOT:integration.adoc[Build Integration]
 

docs/modules/cli/pages/jbang-lock.adoc

@@ -0,0 +1,33 @@
+// Manual page for new lock command (until picocli docs are regenerated)
+:doctype: manpage
+:manmanual: jbang Manual
+:man-linkstyle: pass:[blue R < >]
+= jbang-lock(1)
+
+== Name
+
+jbang-lock - Generate or refresh lock entries for script references.
+
+== Synopsis
+
+*jbang lock* [*--lock-file*=_<lockFile>_] [*--algorithm*=_<algorithm>_] [_<scriptOrFile>_]
+
+== Description
+
+Resolves the given reference and writes lock metadata to a lock file.
+
+Entries include:
+
+- Root digest (`ref=sha256:...`)
+- Resolved source manifest (`ref.sources=...`) when available
+- Resolved transitive dependency coordinates (`ref.deps=...`) when available
+
+== Options
+
+*--algorithm*=_<algorithm>_: `sha256` by default.
+
+*--lock-file*=_<lockFile>_: path to lock file, default is `.jbang.lock`.
+
+== Arguments
+
+[_<scriptOrFile>_]: reference to lock (alias, URL, GAV, file, etc.).

docs/modules/cli/pages/jbang-run.adoc

@@ -122,6 +122,15 @@ Builds and runs provided script. (default command)
 *--manifest*=_<String=String>_::
 
 
+*--lock-file*=_<lockFile>_::
+  Path to lock file (default: .jbang.lock)
+
+*--lock-write*::
+  Write/update digest entry in the lock file for this ref.
+
+*--locked*::
+  Require matching lock entry and enforce lock checks.
+
 *--module*[=_<module>_]::
   Treat resource as a module. Optionally with the given module name
 
@@ -149,6 +158,9 @@ Builds and runs provided script. (default command)
 *-T*, *--source-type*=_<forceType>_::
   Force input to be interpreted as the given type. Can be: java, jshell, groovy, kotlin, or markdown
 
+*--verify*=_<digest>_::
+  Verify script content with digest, e.g. `sha256:abc123`.
+
 *--verbose*::
   jbang will be verbose on what it does.