Normalize commons cards to runtime execute and enforce class-specific entry semantics

CHANGELOG.md

@@ -13,25 +13,29 @@ This changelog records release-line differences that are visible in the checked-
 - Current-line reliance on `_shared` composition or inherited card structure.
 - Deprecated descriptive fields from the current `v1.1.0` card surface, including `slug`, `display_name`, `description`, `capabilities`, and `meta`.
 - Migration-era assumptions that treated older descriptor-led or packaging patterns as part of the active release path.
+- The stale assumption that every Agent Card entry is x402-routed.
 
 ### Structural changes
 
 - `v1.1.0` cards are flat and live directly under `agents/v1.1.0/`.
 - Current cards bind directly to tagged Commons and Commercial schema URLs plus explicit `commandlayer.org` mirror URLs.
+- Commons cards now publish the canonical runtime execute entry, while commercial cards continue to publish semver-pinned x402 routes.
 - Root repository artifacts are the authority surface for the current line, while `dist-pin/agent-cards/v1.1.0/` is a committed derivative bundle that must remain reproducible from the root.
-- Validation for the current line includes schema/card integrity, manifest alignment, canonical root checksum coverage, and derivative-bundle reproducibility.
+- Validation for the current line includes schema/card integrity, manifest alignment, class-sensitive entry enforcement, canonical root checksum coverage, and derivative-bundle reproducibility.
 
 ### Legacy status
 
 - `v1.0.0` remains in-tree only as an archival compatibility line.
 - Legacy `v1.0.0` materials may still include broader card fields, `_shared` schema structure, and older descriptor or publication assumptions that do not apply to the `v1.1.0` authority path.
 - Legacy artifacts are retained for migration review and compatibility, not as the preferred source for new integrations.
+- The repository now also normalizes archived commons card data to the runtime execute entry so the repo no longer carries mixed commons execution semantics.
 
 ### Migration implications
 
 - Treat `v1.1.0` as the authoritative repository line for current integrations and validation; publication claims still wait on release validation.
 - Update tooling that expected `v1.0.0` shared schema paths, broader descriptive card fields, or older descriptor-led publication layout.
 - Expect current cards to expose only the minimal binding fields required by the `v1.1.0` schema.
+- Enforce `entry` by class: commons use `https://runtime.commandlayer.org/execute`, commercial uses `x402://<agent>/<verb>/v1.1.0`.
 - Use the root package commands, especially `npm run validate` and `npm run validate:release`, when reviewing or publishing the current line.
 
 ## [1.0.0]

ONBOARDING.md

@@ -21,6 +21,8 @@ Agent Cards v1.1.0 is the current release-candidate line. Root repository artifa
 Do not add new `_shared` helpers for v1.1.0.
 Do not add descriptive fields to current-line cards; if the detail is not a binding fact, keep it in external documentation or in the linked protocol schemas instead.
 
+Remember the execution split when editing cards: commons cards are runtime-first and must use `https://runtime.commandlayer.org/execute`, while commercial cards remain x402-routed with semver-pinned `x402://<agent>/<verb>/...` entries.
+
 ## Historical scripts
 
 The `scripts/archive/` directory is retained for historical reference only. It is not part of the current `v1.1.0` workflow and should not be treated as an active or supported execution path.
@@ -37,8 +39,8 @@ Use the supported root package scripts and current commands instead: `npm run va
 ## Update flow for the current line
 
 1. edit the canonical root artifact under the correct `v1.1.0` path
-2. keep `$schema`, `$id`, `version`, `entry`, and schema URLs aligned
-3. update `meta/manifest.json` and related registry/discovery pointers if routing changes
+2. keep `$schema`, `$id`, `version`, class-specific `entry`, and schema URLs aligned
+3. update `meta/manifest.json` and related registry/discovery pointers if routing changes or the commons/commercial split changes
 4. rebuild the committed derivative publish bundle at `dist-pin/agent-cards/v1.1.0/` with `node scripts/build-dist-pin.mjs`
 5. regenerate `checksums.txt` with `node scripts/generate-checksums.mjs`
 6. update `RESOLUTION.md`

README.md

@@ -1,11 +1,25 @@
 # CommandLayer Agent Cards
 
-Agent Cards are CommandLayer's canonical discovery and binding artifacts. They bind ENS names to a single verb, the authoritative request/receipt schemas for that verb, the public schema mirrors, and the semver-pinned x402 entrypoint. They do not act as product pages, feature summaries, or semantic substitutes for the linked protocol schemas.
+Agent Cards are CommandLayer's canonical discovery and binding artifacts. They bind ENS names to a single verb, the authoritative request/receipt schemas for that verb, the public schema mirrors, and the class-specific execution entry used to invoke that card. They do not act as product pages, feature summaries, or semantic substitutes for the linked protocol schemas.
 
-In these cards, `x402://...` is the protocol-form entry identifier used by CommandLayer agents. It represents a standardized action endpoint (verb + route + version). This repository may interoperate with x402-related payment context where relevant, but it does not define x402 itself; see the external x402 protocol specification at `https://docs.x402.org/` for the canonical protocol definition.
+The repository now makes the execution split explicit:
+
+- **Commons cards** are runtime-first, free-discovery bindings. Their `entry` is the canonical runtime execute surface: `https://runtime.commandlayer.org/execute`.
+- **Commercial cards** are payment-aware bindings. Their `entry` remains the semver-pinned x402 route: `x402://<agent>/<verb>/v1.1.0`.
+
+This repository may interoperate with x402-related payment context where relevant, but it does not define x402 itself; see the external x402 protocol specification at `https://docs.x402.org/` for the canonical protocol definition.
 
 See `CHANGELOG.md` for version differences.
 
+## Architecture split
+
+CommandLayer Agent Cards now publish two explicit invocation models under one registry:
+
+- **Commons = runtime-first discovery/execution.** Discovery still happens through the card and manifest surfaces, but execution is transported through the canonical runtime `execute` endpoint.
+- **Commercial = x402-routed discovery/execution.** Discovery still happens through the same card and manifest surfaces, while paid execution remains bound to the x402 route for the specific agent verb and release line.
+
+Schemas remain class-specific, and `entry` is therefore class-sensitive rather than universal.
+
 ## x402 compatibility
 
 Commercial CommandLayer flows may reference payment proof or settlement artifacts aligned with the x402 protocol model where applicable. CommandLayer does not define the x402 protocol itself; it interoperates with that payment context as an external protocol surface.
@@ -54,14 +68,15 @@ For `v1.1.0`:
 
 - `schemas.request` and `schemas.receipt` point to the tagged upstream schema source URLs
 - `schemas_mirror.request` and `schemas_mirror.receipt` point to the public `commandlayer.org` mirrors
-- `entry` remains `x402://<ens>/<verb>/v1.1.0`
-- `meta/manifest.json` must exactly match the indexed cards for core binding fields
+- **Commons** `entry` MUST equal `https://runtime.commandlayer.org/execute`
+- **Commercial** `entry` MUST equal `x402://<ens>/<verb>/v1.1.0`
+- `meta/manifest.json` must exactly match the indexed cards for core binding fields, including class-sensitive `entry` values
 
 ### Commons source pattern
 
-`https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json`
+`https://raw.githubusercontent.com/commandlayer/protocol-commons/v1.1.0/schemas/v1.1.0/commons/<verb>/<verb>.request.schema.json`
 
-`https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons/<verb>/<verb>.receipt.schema.json`
+`https://raw.githubusercontent.com/commandlayer/protocol-commons/v1.1.0/schemas/v1.1.0/commons/<verb>/<verb>.receipt.schema.json`
 
 ### Commons mirror pattern
 
@@ -71,9 +86,9 @@ For `v1.1.0`:
 
 ### Commercial source pattern
 
-`https://raw.githubusercontent.com/commandlayer/protocol-commercial/refs/tags/v1.1.0/schemas/v1.1.0/commercial/<verb>/<verb>.request.schema.json`
+`https://raw.githubusercontent.com/commandlayer/protocol-commercial/v1.1.0/schemas/v1.1.0/commercial/<verb>/<verb>.request.schema.json`
 
-`https://raw.githubusercontent.com/commandlayer/protocol-commercial/refs/tags/v1.1.0/schemas/v1.1.0/commercial/<verb>/<verb>.receipt.schema.json`
+`https://raw.githubusercontent.com/commandlayer/protocol-commercial/v1.1.0/schemas/v1.1.0/commercial/<verb>/<verb>.receipt.schema.json`
 
 ### Commercial mirror pattern
 
@@ -148,22 +163,22 @@ agent-cards/
   "class": "commons",
   "implements": ["summarize"],
   "schemas": {
-    "request": "https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons/summarize/summarize.request.schema.json",
-    "receipt": "https://raw.githubusercontent.com/commandlayer/protocol-commons/refs/tags/v1.1.0/schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json"
+    "request": "https://raw.githubusercontent.com/commandlayer/protocol-commons/v1.1.0/schemas/v1.1.0/commons/summarize/summarize.request.schema.json",
+    "receipt": "https://raw.githubusercontent.com/commandlayer/protocol-commons/v1.1.0/schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json"
   },
   "schemas_mirror": {
     "request": "https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.request.schema.json",
     "receipt": "https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json"
   },
-  "entry": "x402://summarizeagent.eth/summarize/v1.1.0",
+  "entry": "https://runtime.commandlayer.org/execute",
   "networks": ["eip155:1"],
   "license": "Apache-2.0",
   "created_at": "2025-11-22T00:00:00Z",
-  "updated_at": "2026-03-19T00:00:00Z"
+  "updated_at": "2026-03-21T00:00:00Z"
 }
 ```
 
-- `npm run validate` — the canonical local validation entrypoint for canonical v1.1.0 cards, discovery descriptors, manifest alignment, and `checksums.txt`
+- `npm run validate` — the canonical local validation entrypoint for canonical v1.1.0 cards, discovery descriptors, manifest alignment, class-sensitive entry validation, and `checksums.txt`
 - `node scripts/build-dist-pin.mjs` — rebuild the committed derivative publish bundle from canonical root files
 - `npm run validate:release` — the canonical release validation entrypoint; it runs `npm run validate` first and then:
   - confirms `meta/manifest.json` matches every current card binding
@@ -183,7 +198,7 @@ The current release review checks:
 - direct Commons and Commercial source URL patterns
 - direct `commandlayer.org` mirror URL patterns
 - exact manifest/card cross-validation for indexed current-line entries
-- entry URI correctness
+- class-sensitive `entry` correctness
 - checksum determinism across authoritative root artifacts, plus separate derivative-bundle verification for `dist-pin/`, so each release surface can be reviewed without blurring authority
 
 ## Release procedure
@@ -199,7 +214,7 @@ Use one clean ceremony from "ready" to public release. Do not substitute alterna
 7. Create the release tag from that exact validated commit.
 8. Push the commit and tag.
 9. Run the final public verification: `npm run validate:release -- --require-mirrors` only after upstream tags and `commandlayer.org` mirrors are expected to be live.
-10. Confirm the public release artifacts resolve from the pushed tag, published checksum set, upstream schema tags, and mirrors before announcing completion.
+10. Confirm the public release artifacts resolve from the pushed tag, published checksum set, upstream schema tags, runtime execute surface documentation, and mirrors before announcing completion.
 
 Recommended command order for maintainers:
 
@@ -213,7 +228,7 @@ git push origin main --follow-tags
 npm run validate:release -- --require-mirrors
 ```
 
-This keeps the trust story narrow: root artifacts are canonical, `dist-pin/` is a committed derivative publish bundle, `.well-known/` remains discovery-only, checksum verification is explicit, and the pushed tag plus checksums identify the release snapshot. If external publish surfaces are not live yet, the release is not fully verified; do not hide that state.
+This keeps the trust story narrow: root artifacts are canonical, `dist-pin/` is a committed derivative publish bundle, `.well-known/` remains discovery-only, checksum verification is explicit, the split between commons runtime execution and commercial x402 routing is explicit, and the pushed tag plus checksums identify the release snapshot. If external publish surfaces are not live yet, the release is not fully verified; do not hide that state.
 
 ## Release surfaces
 

RESOLUTION.md

@@ -16,3 +16,9 @@ This log records formal repository-level decisions that affect the canonical Age
 - **Decision:** Make `npm run validate` the current-line authority path, keep legacy validation explicit and secondary, remove committed placeholder mirror URLs from legacy commercial cards, and document legacy/provenance boundaries directly.
 - **Rationale:** The repository's operational center is `v1.1.0`. Validation and documentation should make that obvious while still preserving `v1.0.0` as a compatibility line. Legacy artifacts should not retain visibly fabricated placeholder values.
 - **Affected artifacts:** `package.json`, `scripts/validate-cards.mjs`, `.github/workflows/validate.yml`, `agents/v1.0.0/commercial/*.json`, `README.md`, `COMPLIANCE.md`, `GOVERNANCE.md`, `SECURITY_PROVENANCE.md`.
+
+### 2026-03-21 — Commons/runtime split made explicit across cards, schemas, and release metadata
+
+- **Decision:** Normalize all commons cards to the canonical runtime execute entry, preserve x402 routing only for commercial cards, and enforce the split in schemas, validation, manifests, dist-pin artifacts, and repository documentation.
+- **Rationale:** The repository should publish one coherent invocation model: commons are runtime-first and non-x402 at entry, while commercial cards remain payment-aware and x402-routed. Leaving mixed semantics in cards, docs, or validators would make the release contract misleading.
+- **Affected artifacts:** `agents/v1.0.0/commons/*.json`, `agents/v1.1.0/commons/*.json`, `schemas/v1.0.0/_shared/agent.card.base.schema.json`, `schemas/v1.1.0/agent.card.schema.json`, `scripts/validate-cards.mjs`, `meta/manifest.json`, `meta/commons-agent.json`, `meta/commercial-agent.json`, `README.md`, `SPEC.md`, `ONBOARDING.md`, `CHANGELOG.md`, `checksums.txt`, `dist-pin/agent-cards/v1.1.0/**`.