feat: support external material locators (#247)

* Support external material locators

Allow annotated material references and approved connector schemes while preserving notes through pull, review, and export. Keep external access host-managed and report archive portability accurately.

Co-authored-by: Goose <opensource@block.xyz>
Ai-assisted: true

* Name external locator provider, cover mixed arrays, de-duplicate scheme docs

Address review gaps on the external material locator work:

- Export audit names the provider (mcp/figma/github) instead of a flat
  "connection-dependent" label, at the markdown layer only; the export
  JSON access contract is unchanged. Adds externalLocatorScheme() as the
  single source for scheme extraction.
- Add end-to-end coverage for a single node carrying a bare local path, a
  bare https: URL, and an annotated mcp: declaration together through pull,
  and widen export --strict to span mcp:/figma:/github:.
- Collapse the verbatim scheme list from six doc surfaces to one canonical
  enumeration in references/schema.md; other docs defer to it. The code
  allowlist remains the source of truth.

Co-authored-by: Chai Landau <chai@block.xyz>
Signed-off-by: Chai Landau <chai@block.xyz>

* Note externalLocatorScheme and provider-named audit in changeset

The changeset described the two original public helpers but not
externalLocatorScheme(), the third /core export added while naming the
export audit provider. Extend the entry to cover both.

Co-authored-by: Chai Landau <chai@block.xyz>
Signed-off-by: Chai Landau <chai@block.xyz>

---------

Signed-off-by: Chai Landau <chai@block.xyz>
Co-authored-by: Goose <opensource@block.xyz>
Co-authored-by: npub1ph5a5cnj7f3rlw4054e0etpcvd9afzm8ly7gh6zh5nszg2wewmwsxcukkk <0de9da6272f2623fbaafa572fcac38634bd48b67f93c8be857a4e02429d976dd@buzz.block.builderlab.xyz>
Co-authored-by: Chai Landau <chai@block.xyz>

Author: 4 people

.changeset/fuzzy-panthers-connect.md

@@ -0,0 +1,5 @@
+---
+"@design-intelligence/ghost": minor
+---
+
+Accept `https:`, `mcp:`, `figma:`, and `github:` external material locators and annotated `{ locator, note }` declarations. This widens public material arrays from `string[]` to `GhostMaterial[]`; TypeScript consumers of `/core` and `/embed` can use `materialLocator()` or `normalizeMaterial()` to read either shape, and `externalLocatorScheme()` to read an external locator's scheme. Pull JSON now includes optional `note`, export audit JSON includes optional `access`, the export audit names the external provider (for example `mcp`, `figma`, or `github`), and external-material omission messages use the new locator terminology.

CLAUDE.md

@@ -58,10 +58,12 @@ hierarchy, no inheritance, no edges; nesting into folders is a browsing
 convenience only.
 
 `materials` is the single locator field for concrete materials the guidance is
-about. It accepts repo-relative paths/globs and absolute HTTPS URLs. Components,
-patterns, logos, motion files, illustrations, and external asset libraries all
-use the same field. Guidance stays in prose; `materials` only says where the
-material is.
+about. It accepts repo-relative paths/globs and supported external locators as
+bare strings or `{ locator, note }` objects. Components, patterns, logos, motion
+files, illustrations, and external asset libraries all use the same field.
+Guidance stays in prose; `materials` only says where the material is. See
+`packages/ghost/src/skill-bundle/references/schema.md` for the supported
+external locator schemes.
 
 While drafting a body, ask three questions of every node (drafting prompts,
 never fields): **why** (the stance), **with what** (the materials, and pointers

README.md

@@ -122,8 +122,9 @@ Use the full lockup when recognition matters. Use the glyph only when space is
 constrained or when brand presence should recede.
 ```
 
-`materials` is a list of paths or URLs pointing at the concrete stuff the
-guidance is about: repo-relative paths/globs or absolute HTTPS URLs. Components,
+`materials` points at the concrete stuff the guidance is about through
+repo-relative paths/globs or supported external references. An opaque entry may
+include a short note describing what the agent will find there. Components,
 patterns, logos, motion files, illustrations, and external asset libraries all
 use the same field. Guidance stays in prose; `materials` only says where the
 material is.

docs/purposes.md

@@ -38,7 +38,7 @@ into folders is a browsing convenience only.
 | `manifest.yml` | Schema version and package id; the package's anchor. |
 | `glossary.md` | The author's dictionary: every term with defined meaning in the corpus. ghost ships no fixed vocabulary. |
 | Prose nodes (`<kind>.<slug>.md`, `<slug>.md`) | Durable brand guidance; each body answers why (the stance), with what (the materials), or how it is assembled (the patterns). Altitude lives in prose; narrower guidance names its condition. |
-| Node frontmatter | `description` (retrieval payload) and optional `materials` (repo-relative paths/globs or HTTPS URLs for concrete materials the prose governs). |
+| Node frontmatter | `description` (retrieval payload) and optional `materials` (repo-relative paths/globs or supported external locators, with optional retrieval notes; see the schema reference for the supported schemes). |
 | `checks/` | Optional review assertions binding to nodes with `references`. Never a node source and never generation input. |
 
 One resolution mechanism, read-only:
@@ -87,7 +87,8 @@ Two rules keep the reservation honest:
 
 3. **Guidance smuggled into `materials`.** A material locator list that starts
    carrying roles, rules, or semantic metadata becomes a second schema.
-   *Fix: keep `materials` as strings only; write meaning in the node body.*
+   *Fix: allow a short retrieval note when a locator is opaque, but keep roles,
+   rules, and meaning in the node body.*
 
 4. **Checks becoming generation input.** Checks are feedback assertions. If they
    appear in `gather`, the model starts writing to the test and the review

packages/ghost/src/commands/export-command.ts

@@ -3,7 +3,9 @@ import { dirname, resolve } from "node:path";
 import type { CAC } from "cac";
 import {
   classifyMaterialLocator,
+  externalLocatorScheme,
   type GhostCatalogNode,
+  materialLocator,
   resolveLocalMaterialLocator,
   type TransportedMaterialTier,
 } from "#ghost-core";
@@ -26,6 +28,7 @@ interface ExportAuditTravelingLocator {
   nodeId: string;
   locator: string;
   tier: Extract<TransportedMaterialTier, "bundled" | "url">;
+  access?: "https" | "connector";
 }
 
 interface ExportAuditStrandedLocator {
@@ -161,10 +164,16 @@ function auditNodeMaterials(
   travels: ExportAuditTravelingLocator[],
   stranded: ExportAuditStrandedLocator[],
 ): void {
-  for (const locator of node.materials ?? []) {
+  for (const material of node.materials ?? []) {
+    const locator = materialLocator(material);
     const classified = classifyMaterialLocator(locator);
     if (classified.kind === "url") {
-      travels.push({ nodeId: node.id, locator, tier: "url" });
+      travels.push({
+        nodeId: node.id,
+        locator,
+        tier: "url",
+        access: classified.access,
+      });
       continue;
     }
 
@@ -213,8 +222,22 @@ function formatExportMarkdown(fields: {
   if (fields.audit.travels.length > 0) {
     lines.push("Travels with the archive:", "");
     for (const item of fields.audit.travels) {
-      const label = item.tier === "url" ? "HTTPS URL" : "bundled material";
-      lines.push(`- \`${item.nodeId}\` — \`${item.locator}\` (${label})`);
+      if (item.access === "connector") {
+        const provider = externalLocatorScheme(item.locator) ?? "connector";
+        lines.push(
+          `- \`${item.nodeId}\` — \`${item.locator}\` (${provider} external locator only)`,
+          `  - The locator travels; the recipient may need a ${provider} connection or permission to access the material.`,
+        );
+      } else if (item.access === "https") {
+        lines.push(
+          `- \`${item.nodeId}\` — \`${item.locator}\` (HTTPS external locator only)`,
+          "  - The locator travels; access depends on the URL and any permissions it requires.",
+        );
+      } else {
+        lines.push(
+          `- \`${item.nodeId}\` — \`${item.locator}\` (bundled material)`,
+        );
+      }
     }
   } else {
     lines.push("Travels with the archive: none.");

packages/ghost/src/commands/pull-command.ts

@@ -160,21 +160,25 @@ function appendMaterialMarkdown(
 ): void {
   if (material.inlined !== undefined) {
     const info = material.path ?? material.locator;
-    lines.push("", fencedMarkdown(material.inlined.trimEnd(), info));
-  } else if (material.reason === "binary inspect-pointer") {
-    lines.push(
-      `- inspect: ${material.path ?? material.locator} — view this image before generating`,
-    );
-  } else {
-    const reason = material.omitted
-      ? ` — ${material.reason ?? "not inlined"}`
-      : "";
-    lines.push(`- ${material.locator}${reason}`);
+    lines.push("");
+    if (material.note !== undefined) {
+      lines.push(`Note for \`${material.locator}\`: ${material.note}`, "");
+    }
+    lines.push(fencedMarkdown(material.inlined.trimEnd(), info));
+    return;
   }
+
+  const target =
+    material.reason === "binary inspect-pointer"
+      ? `inspect: ${material.path ?? material.locator} — view this image before generating`
+      : `${material.locator}${material.omitted ? ` — ${material.reason ?? "not inlined"}` : ""}`;
+  lines.push(`- ${target}`);
+  if (material.note !== undefined) lines.push(`  Note: ${material.note}`);
 }
 
 function formatJsonMaterial(material: TransportedMaterial): {
   locator: string;
+  note?: string;
   tier: TransportedMaterial["tier"];
   inlined?: string;
   omitted?: true;
@@ -183,6 +187,7 @@ function formatJsonMaterial(material: TransportedMaterial): {
 } {
   return {
     locator: material.locator,
+    ...(material.note !== undefined ? { note: material.note } : {}),
     tier: material.tier,
     ...(material.inlined !== undefined ? { inlined: material.inlined } : {}),
     ...(material.omitted

packages/ghost/src/embed/inspect.ts

@@ -3,9 +3,11 @@ import { TextDecoder } from "node:util";
 import {
   classifyMaterialLocator,
   expandLocalMaterialLocator,
+  type GhostMaterial,
   hasGlobMagic,
   inferMaterialMime,
   isTextMime,
+  materialLocator,
   materialLocatorClaimsPath,
   resolveContainedRealFile,
   resolveLocalMaterialLocator,
@@ -205,20 +207,21 @@ export async function inspectGhostMaterial(
 }
 
 function declaredMaterialLocator(
-  declared: readonly string[],
+  declared: readonly GhostMaterial[],
   requested: string,
   repoRoot: string,
   packageDir: string,
 ): string | undefined {
-  if (declared.includes(requested)) return requested;
+  const locators = declared.map(materialLocator);
+  if (locators.includes(requested)) return requested;
   const requestedKind = classifyMaterialLocator(requested);
   if (requestedKind.kind !== "local") return undefined;
   const requestedPath = resolveLocalMaterialLocator(requested, {
     repoRoot,
     packageDir,
     materialsDir: GHOST_MATERIALS_DIR,
   }).pattern;
-  return declared.find(
+  return locators.find(
     (locator) =>
       hasGlobMagic(locator) &&
       materialLocatorClaimsPath(locator, requestedPath, {

packages/ghost/src/embed/pull.ts

@@ -3,7 +3,9 @@ import {
   closestIds,
   extractSkeletonFences,
   type GhostCatalogNode,
+  type GhostMaterial,
   type MaterialTransportResult,
+  normalizeMaterial,
   resolveLocalMaterialLocator,
   stripSkeletonSections,
   transportMaterials,
@@ -122,22 +124,26 @@ function steeringBucket(
 }
 
 function locatorOnlyMaterials(
-  locators: readonly string[] | undefined,
+  declarations: readonly GhostMaterial[] | undefined,
   repoRoot: string,
   packageDir: string,
 ): MaterialTransportResult {
   return {
-    materials: (locators ?? []).map((locator) => ({
-      locator,
-      tier:
-        classifyMaterialLocator(locator).kind === "url"
-          ? "url"
-          : resolveLocalMaterialLocator(locator, {
-              repoRoot,
-              packageDir,
-              materialsDir: GHOST_MATERIALS_DIR,
-            }).tier,
-    })),
+    materials: (declarations ?? []).map((declaration) => {
+      const { locator, note } = normalizeMaterial(declaration);
+      return {
+        locator,
+        ...(note !== undefined ? { note } : {}),
+        tier:
+          classifyMaterialLocator(locator).kind === "url"
+            ? "url"
+            : resolveLocalMaterialLocator(locator, {
+                repoRoot,
+                packageDir,
+                materialsDir: GHOST_MATERIALS_DIR,
+              }).tier,
+      };
+    }),
     inlined: 0,
     omitted: 0,
   };

packages/ghost/src/embed/types.ts

@@ -2,6 +2,7 @@ import type {
   CatalogMenuEntry,
   GhostCatalogNode,
   GhostGlossaryKind,
+  GhostMaterial,
   GhostPackageManifest,
   TransportedMaterial,
 } from "#ghost-core";
@@ -108,7 +109,7 @@ export interface GhostPulledNode {
   id: string;
   kind?: string;
   description?: string;
-  declaredMaterials?: readonly string[];
+  declaredMaterials?: readonly GhostMaterial[];
   materials?: readonly TransportedMaterial[];
   body: string;
 }

packages/ghost/src/ghost-core/catalog/types.ts

@@ -1,3 +1,5 @@
+import type { GhostMaterial } from "../materials.js";
+
 /**
  * A node in the fingerprint catalog — pure prose plus its filename-derived
  * identity. The body is the design expression; there are no structured content
@@ -12,8 +14,8 @@ export interface GhostCatalogNode {
   slug: string;
   /** Retrieval payload shown in gather: what applies, when, and what it contributes. */
   description?: string;
-  /** Optional material locators carried by the authored node. */
-  materials?: string[];
+  /** Optional bare or annotated material locators carried by the authored node. */
+  materials?: GhostMaterial[];
   /** True when the node carries a material locator, substantial fence, or Skeleton. */
   concrete: boolean;
   /** True when the node body carries a fenced block of at least 3 lines. */