From f00feb71fdf311a721b5fd41b9d8877d2f048315 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 30 Oct 2026 00:35:33 +0000
Subject: [PATCH] fix(cli): name the ECMA-427 identity grammar in the usage
 text

The usage text still advertised pkg:<vcs>/<host>/<path>, which svn and hg identities now refuse; it and the lock's Resource comment name the pkg:generic form and the two input spellings.

Co-Authored-By: jason.han <hanhuijun@gmail.com>
---
 changes/unreleased/help-identity-grammar.fixed.md | 1 +
 cmd/syspi/main.go                                 | 8 ++++++--
 internal/lock/lock.go                             | 4 ++--
 3 files changed, 9 insertions(+), 4 deletions(-)
 create mode 100644 changes/unreleased/help-identity-grammar.fixed.md

diff --git a/changes/unreleased/help-identity-grammar.fixed.md b/changes/unreleased/help-identity-grammar.fixed.md
new file mode 100644
index 0000000..ec00195
--- /dev/null
+++ b/changes/unreleased/help-identity-grammar.fixed.md
@@ -0,0 +1 @@
+- `syspi -h` names the ECMA-427 identity grammar and the two input spellings it normalises, instead of the refused `pkg:<vcs>/<host>/<path>` form.
diff --git a/cmd/syspi/main.go b/cmd/syspi/main.go
index 487c37b..2ee2eb2 100644
--- a/cmd/syspi/main.go
+++ b/cmd/syspi/main.go
@@ -39,8 +39,12 @@ Commands:
   bundle    build a deterministic .kpar from a project directory
   version   print the version
 
-A package is any git, svn or hg repository with .project.json at a tag:
-  pkg:<vcs>/<host>/<path>[@<version>][#<subpath>]
+A package is any git, svn or hg repository with .project.json at a tag, identified by an
+ECMA-427 Package-URL (vcs: git, svn, hg; transports per Annex B.3.5, plus file):
+  pkg:generic/<name>?vcs_url=<vcs>%2B<transport>:%2F%2F<host>%2F<path>[%40<version>][%23<subpath>]
+Accepted as input and normalised to it:
+  pkg:git/<host>/<path>[@<version>][#<subpath>]
+  <vcs>+<transport>://<host>/<path>[@<version>][#<subpath>]
 Run "syspi <command> -h" for the flags of a command.
 `
 
diff --git a/internal/lock/lock.go b/internal/lock/lock.go
index 05fcbce..fd712c9 100644
--- a/internal/lock/lock.go
+++ b/internal/lock/lock.go
@@ -27,8 +27,8 @@ const (
 
 // Entry is one locked package.
 type Entry struct {
-	// Resource is the canonical, version-free identity (pkg:<vcs>/<host>/<path>[#<subpath>],
-	// an archive URL or path, a standard IRI).
+	// Resource is the canonical, version-free identity (pkg:generic/<name>?vcs_url=… without
+	// the %40<version>, an archive URL or path, a standard IRI).
 	Resource  string `json:"resource"`
 	Kind      string `json:"kind"`
 	Publisher string `json:"publisher,omitempty"`