fix: AGENTS.md compliance -- encoding, docs, changelog

Vicente-Pastor · Copilot · Vicente-Pastor · commit 516370aa043a · 2026-04-13T17:27:53.000+01:00
- Replace non-ASCII arrows (U+2192) and section sign (U+00A7) with ASCII - Update cli-commands.md with URL marketplace add syntax and examples - Update marketplace group description to mention URL sources - Add PR number (#691) alongside issue number (#676) in CHANGELOG Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,12 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `apm marketplace add <URL>` accepts HTTPS URLs for registering Agent Skills discovery indexes, with automatic `.well-known/agent-skills/index.json` resolution for bare origins (#676)
-- Agent Skills Discovery RFC v0.2.0 index parser with strict `$schema` validation, skill name rules, and digest verification (#676)
-- SHA-256 digest computation and integrity verification for URL-based marketplace indexes (#676)
-- ETag/Last-Modified conditional refresh for URL marketplace indexes with stale-while-revalidate fallback (#676)
-- Archive download and extraction support for `type: "archive"` skill entries with path traversal and decompression bomb safety guards (#676)
-- Lockfile provenance fields (`source_url`, `source_digest`) for URL-sourced marketplace dependencies (#676)
+- `apm marketplace add <URL>` accepts HTTPS URLs for registering Agent Skills discovery indexes, with automatic `.well-known/agent-skills/index.json` resolution for bare origins (#676, #691)
+- Agent Skills Discovery RFC v0.2.0 index parser with strict `$schema` validation, skill name rules, and digest verification (#676, #691)
+- SHA-256 digest computation and integrity verification for URL-based marketplace indexes (#676, #691)
+- ETag/Last-Modified conditional refresh for URL marketplace indexes with stale-while-revalidate fallback (#676, #691)
+- Archive download and extraction support for `type: "archive"` skill entries with path traversal and decompression bomb safety guards (#676, #691)
+- Lockfile provenance fields (`source_url`, `source_digest`) for URL-sourced marketplace dependencies (#676, #691)
 - `apm install` now automatically discovers and deploys local `.apm/` primitives (skills, instructions, agents, prompts, hooks, commands) to target directories, with local content taking priority over dependencies on collision (#626, #644)
 
 ### Fixed
diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md
@@ -937,7 +937,7 @@ apm mcp show a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1
 
 ### `apm marketplace` - Plugin marketplace management
 
-Register, browse, and manage plugin marketplaces. Marketplaces are GitHub repositories containing a `marketplace.json` index of plugins.
+Register, browse, and manage plugin marketplaces. Marketplaces are GitHub repositories containing a `marketplace.json` index of plugins, or HTTPS URLs serving an Agent Skills Discovery index.
 
 > See the [Marketplaces guide](../../guides/marketplaces/) for concepts and workflows.
 
@@ -947,26 +947,28 @@ apm marketplace COMMAND [OPTIONS]
 
 #### `apm marketplace add` - Register a marketplace
 
-Register a GitHub repository as a plugin marketplace.
+Register a GitHub repository or HTTPS URL as a plugin marketplace.
 
 ```bash
 apm marketplace add OWNER/REPO [OPTIONS]
 apm marketplace add HOST/OWNER/REPO [OPTIONS]
+apm marketplace add URL [OPTIONS]
 ```
 
 **Arguments:**
 - `OWNER/REPO` - GitHub repository containing `marketplace.json`
 - `HOST/OWNER/REPO` - Repository on a non-github.com host (e.g., GitHub Enterprise)
+- `URL` - HTTPS URL to an Agent Skills Discovery index (bare origins auto-resolve to `/.well-known/agent-skills/index.json`)
 
 **Options:**
 - `-n, --name TEXT` - Custom display name for the marketplace
-- `-b, --branch TEXT` - Branch to track (default: main)
-- `--host TEXT` - Git host FQDN (default: github.com or `GITHUB_HOST` env var)
+- `-b, --branch TEXT` - Branch to track (default: main; GitHub sources only)
+- `--host TEXT` - Git host FQDN (default: github.com or `GITHUB_HOST` env var; GitHub sources only)
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
 ```bash
-# Register a marketplace
+# Register a GitHub marketplace
 apm marketplace add acme/plugin-marketplace
 
 # Register with a custom name and branch
@@ -975,6 +977,12 @@ apm marketplace add acme/plugin-marketplace --name acme-plugins --branch release
 # Register from a GitHub Enterprise host
 apm marketplace add acme/plugin-marketplace --host ghes.corp.example.com
 apm marketplace add ghes.corp.example.com/acme/plugin-marketplace
+
+# Register a URL-based marketplace (bare origin)
+apm marketplace add https://plugins.example.com
+
+# Register with full index URL and custom name
+apm marketplace add https://plugins.example.com/.well-known/agent-skills/index.json --name company-skills
 ```
 
 #### `apm marketplace list` - List registered marketplaces
diff --git a/src/apm_cli/marketplace/client.py b/src/apm_cli/marketplace/client.py
@@ -269,7 +269,7 @@ def _fetch_url_direct(url: str, *, etag: str = "", last_modified: str = "",
         if last_modified:
             headers["If-Modified-Since"] = last_modified
         resp = requests.get(url, headers=headers, timeout=30)
-        # Guard against HTTPS→HTTP redirect (S1)
+        # Guard against HTTPS->HTTP redirect (S1)
         final_url = getattr(resp, "url", None)
         if isinstance(final_url, str) and urlparse(final_url).scheme.lower() != "https":
             raise MarketplaceFetchError(
diff --git a/tests/unit/marketplace/test_marketplace_url_client.py b/tests/unit/marketplace/test_marketplace_url_client.py
@@ -833,7 +833,7 @@ class TestFetchUrlDirectRedirectEnforcement:
     """_fetch_url_direct must reject responses redirected to non-HTTPS URLs."""
 
     def test_redirect_to_http_raises(self, monkeypatch):
-        """An HTTPS→HTTP redirect must be caught after the request completes."""
+        """An HTTPS->HTTP redirect must be caught after the request completes."""
         mock_resp = _mock_response(200, json_body=_AGENT_SKILLS_INDEX)
         mock_resp.url = "http://evil.com/index.json"
         monkeypatch.setattr(
@@ -844,7 +844,7 @@ def test_redirect_to_http_raises(self, monkeypatch):
             _fetch_url_direct("https://example.com/index.json")
 
     def test_redirect_to_https_accepted(self, monkeypatch):
-        """HTTPS→HTTPS redirect is fine."""
+        """HTTPS->HTTPS redirect is fine."""
         mock_resp = _mock_response(200, json_body=_AGENT_SKILLS_INDEX)
         mock_resp.url = "https://cdn.example.com/index.json"
         monkeypatch.setattr(
diff --git a/tests/unit/marketplace/test_marketplace_url_commands.py b/tests/unit/marketplace/test_marketplace_url_commands.py
@@ -106,7 +106,7 @@ def test_http_url_rejected(self, runner):
         "HTTP://example.com",
     ])
     def test_mixed_case_scheme_detected_as_url(self, runner, url):
-        """URL detection must be case-insensitive per RFC 3986 §3.1."""
+        """URL detection must be case-insensitive per RFC 3986 Section 3.1."""
         from apm_cli.commands.marketplace import marketplace
 
         result = runner.invoke(marketplace, ["add", url])
@@ -438,7 +438,7 @@ class TestAddCommandErrorMessages:
 
     @patch("apm_cli.marketplace.client.fetch_marketplace")
     def test_schema_error_shows_invalid_index_format(self, mock_fetch, runner):
-        """T9: wrong $schema → 'Invalid index format', not generic 'Failed to register'."""
+        """T9: wrong $schema -> 'Invalid index format', not generic 'Failed to register'."""
         from apm_cli.commands.marketplace import marketplace
 
         mock_fetch.side_effect = ValueError(
