Skip to content

ARD Catalog Marketplace Source

An ARD Catalog source lets SkillMeat crawl an external publisher domain that exposes an Agentic Resource Discovery catalog at https://<domain>/.well-known/ai-catalog.json, normalize the published entries into import candidates, and route them through SkillMeat's existing import approval workflow. Discovered entries are never auto-imported — you review and approve each one, exactly like any other marketplace source.

Feature flag. ARD Catalog sources are gated behind SKILLMEAT_ARD_CATALOG_CONSUMER_ENABLED and are OFF by default. Set SKILLMEAT_ARD_CATALOG_CONSUMER_ENABLED=true in the API environment to enable the source type. With the flag off, the ARD endpoints return 404 and the type is hidden from the UI.

Security model

  • SSRF guard. Every catalog/entry URL is validated by validate_fetch_url() before any network fetch: only https:// is allowed, and any URL resolving to a private, loopback, link-local, or otherwise reserved IP range is rejected.
  • Advisory-only trust. A publisher's self-attested trustManifest is recorded as advisory metadata only. It can never change a source's trust_level, approved, or disposition. A high self-claimed score still lands as disposition="pending" and must be approved by you.
  • Tenancy (enterprise). In enterprise mode, imported rows take their tenant_id from your authenticated session — never from the catalog entry.

Add a source — Web UI

  1. Open Marketplace → Sources and click Add Source.
  2. In the source-type picker, choose ARD Catalog.
  3. Enter the publisher domain / catalog URL in the Catalog URL field. It must be https:// (a client-side hint enforces this); private/loopback hosts are rejected by the server.
  4. Optionally set a registry URL, advisory trust tier, description, and tags.
  5. Save. The new source appears as a card showing source_type: ard_catalog and the catalog domain.

Browse & import discovered entries — Web UI

  1. From the ARD source, trigger a refresh to crawl the catalog.
  2. The discovered-entries panel lists entries with their source_domain, a relevance score (used for display sorting only — it never drives auto-import), and a disposition badge (new / duplicate).
  3. Click Import on an entry to route it into the standard approval workflow.
  4. Imported artifacts carry an ard_urn of the form urn:air:<domain>:<type>:<name>. Non-ARD artifacts simply have no URN field — nothing is shown.

CLI

# Add an ARD catalog source (prints the new source ID)
skillmeat marketplace source add --type ard_catalog --url example.com

# List sources (ARD sources show their catalog domain)
skillmeat marketplace source list

# Refresh / crawl a source (prints entries found + new/duplicate counts)
skillmeat marketplace source refresh <SOURCE_ID>

If the feature flag is off, the CLI surfaces a friendly "feature disabled" message rather than a raw error.

How it works

ARD publisher domain  ──crawl──▶  ard_catalog_broker
  /.well-known/ai-catalog.json    │  (SSRF-guarded fetch, ARD v0.9 mapping,
                                  │   raw entry JSON preserved in metadata_json)
                                  ▼
                            ard_adapter (ARDImportAdapter)
                                  │  (entry → ImportCoordinator dict shape;
                                  │   stamps origin="ard_catalog", ard_urn)
                                  ▼
                       existing ImportCoordinator approval gate
                                  │  (no auto-import; you approve each entry)
                                  ▼
                            your collection

Limitations (v1 — register + discover/preview only)

v1 ships the security foundation and discovery/preview path. Two capabilities are deferred to a follow-on slice (documented design specs under docs/project_plans/design-specs/):

  • Importing discovered entries is not yet wired. You can register an ARD source and preview its discovered entries (with new/duplicate dispositions), but the "Import" action does not yet stage ARD entries into your collection — refresh is preview-only and does not persist catalog rows. See ard-import-roundtrip-wiring.md.
  • Advisory trust is parsed but not persisted/displayed. A publisher trustManifest is not yet recorded as advisory provenance. See ard-trust-advisory-persistence.md. (The advisory-only invariant — self-attested trust can never elevate a source — holds regardless.)

Additionally, this is the consumer slice only: SkillMeat does not publish its own /.well-known/ai-catalog.json, expose an ARD registry search endpoint, or persist a typed URN column — tracked as deferred design specs gated on ARD v1.0 ratification.