Make Relay runtime config-driven

.changeset/relay-context-packets.md

@@ -0,0 +1,5 @@
+---
+"@anarchitecture/ghost": minor
+---
+
+Adds Relay context JSON, structured Relay requests, and config-driven runtime selection for declared project context sources.

apps/docs/src/content/docs/cli-reference.mdx

@@ -136,16 +136,25 @@ reusable review prompt.
 
 ### Agent Context - `relay gather`
 
-Gather a compact Relay brief from the resolved fingerprint stack for a target
-path. Use this before generation so the host agent starts with the package
-stack, intent, active obligations, composition, inventory, validation checks,
-and gaps.
+Gather Relay context for a target path or structured Relay request. Relay loads
+config first; omitted `base` means `base.kind: fingerprint`, while
+`base.kind: none` lets agent-framework repos gather declared request context
+without a `.ghost` package. For agents and host adapters, use JSON: the full
+`ghost.relay.gather/v2` result is the stable contract, and its nested `context`
+is `ghost.relay-context/v1`. Plain markdown output remains a compact human
+preview.
 
 <CliHelp tool="ghost" command="relay" hideDescription />
 
 ```bash
-ghost relay gather apps/checkout/review/page.tsx
+ghost relay gather apps/checkout/review/page.tsx --format json
 ghost relay gather apps/checkout/review/page.tsx --package product-surface --format json
+ghost relay gather apps/checkout/review/page.tsx --config .ghost/relay.yml --format json
+GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json
+ghost relay gather stacks/managerbot.cash-flow-gap.push.yml --config .agents/ghost/relay.yml --format json
+ghost relay gather --request request.yml --format json
+ghost relay gather --request-stdin --format json
+ghost relay gather apps/checkout/review/page.tsx # human preview
 ```
 
 ### Inspection - `describe`

apps/docs/src/content/docs/getting-started.mdx

@@ -106,16 +106,29 @@ review for approval. For a fuller human-agent workflow, read
 
 </DocSection>
 
-<DocSection title="Brief From Ghost">
+<DocSection title="Relay Context From Ghost">
 
-Before generating or revising UI, gather a Relay brief for the target path:
+Before generating or revising UI, gather Relay JSON for the target path:
 
 ```bash
-ghost relay gather apps/checkout/review/page.tsx
+ghost relay gather apps/checkout/review/page.tsx --format json
+```
+
+`ghost.relay.gather/v2` is the agent contract. Agents should read `context`,
+`selected_context`, `targetPaths`, `source`, `stackDirs`, gaps, and trace fields
+from JSON. Plain `ghost relay gather <target>` remains a compact human preview.
+For prompt-shaped work where there is no clear path, host agents can create a
+`ghost.relay-request/v1` and run
+`ghost relay gather --request-stdin --format json`.
+Relay config controls the runtime. Omitted `base` uses the resolved fingerprint
+stack; `base.kind: none` lets frameworks provide declared request context
+without a `.ghost` package:
+
+```bash
+GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json
+ghost relay gather stacks/managerbot.cash-flow-gap.push.yml --config .agents/ghost/relay.yml --format json
 ```
 
-Relay compiles selected context from the resolved stack: matched packages,
-intent, active obligations, composition, inventory, validation checks, and gaps.
 The package remains the approved product-surface context; review and check
 commands apply it after implementation.
 

apps/docs/src/generated/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-24T04:21:56.789Z",
+  "generatedAt": "2026-06-24T16:55:39.949Z",
   "tools": [
     {
       "tool": "ghost",
@@ -587,7 +587,7 @@
           "tool": "ghost",
           "name": "relay",
           "rawName": "relay <action> [target]",
-          "description": "Gather fingerprint-grounded context for an agent target.",
+          "description": "Gather Relay context for an agent target.",
           "group": "core",
           "defaultHelp": true,
           "compactName": "relay gather",
@@ -616,6 +616,38 @@
               "default": "markdown",
               "takesValue": true,
               "negated": false
+            },
+            {
+              "rawName": "--config <file>",
+              "name": "config",
+              "description": "Load an explicit Ghost Relay config",
+              "default": null,
+              "takesValue": true,
+              "negated": false
+            },
+            {
+              "rawName": "--request <file>",
+              "name": "request",
+              "description": "Load a structured Ghost Relay request",
+              "default": null,
+              "takesValue": true,
+              "negated": false
+            },
+            {
+              "rawName": "--request-stdin",
+              "name": "requestStdin",
+              "description": "Read a structured Ghost Relay request from stdin",
+              "default": null,
+              "takesValue": false,
+              "negated": false
+            },
+            {
+              "rawName": "--mode <mode>",
+              "name": "mode",
+              "description": "Relay mode: generation, review, or prompt",
+              "default": "generation",
+              "takesValue": true,
+              "negated": false
             }
           ]
         },

docs/fingerprint-format.md

@@ -229,7 +229,8 @@ ghost verify .ghost --root .
 ghost check --base main --format json
 ghost review --base main
 ghost emit review-command --path apps/checkout/review/page.tsx
-ghost relay gather apps/checkout/review/page.tsx
+ghost relay gather apps/checkout/review/page.tsx --format json
+ghost relay gather --request request.yml --format json
 ```
 
 `ghost scan` reports package contribution facets. Useful `intent` means any

docs/generation-loop.md

@@ -22,16 +22,51 @@ deterministic gates + advisory surface-composition findings
 
 ## Before Generation
 
-Build a brief from the resolved fingerprint stack:
+Gather Relay JSON when a target path is known:
 
 ```bash
-ghost relay gather apps/checkout/review/page.tsx
+ghost relay gather apps/checkout/review/page.tsx --format json
 ```
 
-Relay compiles selected context from the resolved stack as context hits:
-fingerprint refs, why they matched, suggested reads, omissions, and gaps.
+By default, Relay uses the resolved `.ghost` fingerprint stack as its base
+runtime. A Relay config can add declared sources, request resolvers, or opt out
+of the fingerprint base entirely with `base.kind: none`.
+
+For prompt-shaped work without a clear path, the host agent should first turn
+the ask into a structured Relay request, then pass it to Ghost:
+
+```yaml
+schema: ghost.relay-request/v1
+task: generate-interface
+selectors:
+  customer: merchant
+  brand: square
+  system: managerbot
+  moment: cash-flow-gap
+  medium: push
+  capability: lending
+```
+
+```bash
+ghost relay gather --request-stdin --format json
+```
 
-Use the brief in this order:
+If the host framework stores Relay config outside `.ghost/relay.yml`, keep the
+same command and pass the config:
+
+```bash
+GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json
+ghost relay gather stacks/managerbot.cash-flow-gap.push.yml --config .agents/ghost/relay.yml --format json
+```
+
+The second form works for `base.kind: none` configs by synthesizing a minimal
+`task: gather` Relay request from the target path.
+
+The full `ghost.relay.gather/v2` result is the agent contract. Agents should
+read `context`, `selected_context`, `targetPaths`, `source`, `stackDirs`, gaps,
+and trace fields from JSON rather than scraping the markdown preview.
+
+Use the JSON context in this order:
 
 1. Start from the selected context hits and their match reasons.
 2. Apply intent and composition hits before choosing implementation details.
@@ -43,6 +78,10 @@ Use the brief in this order:
 7. Treat gaps as a signal to use local evidence provisionally or inspect the
    full facet files.
 
+For quick terminal inspection, `ghost relay gather <target>` still prints a
+compact human preview. The preview can omit projected Relay config sources that
+are present in JSON.
+
 Raw repo signals can help orient an agent:
 
 ```bash
@@ -103,7 +142,9 @@ ghost review --base main --format markdown
 
 Advanced wrappers that store fingerprint packages outside `.ghost` can set
 `GHOST_PACKAGE_DIR=<relative-dir>` on stack-aware commands. `--package <dir>`
-remains exact single-bundle mode and bypasses stack discovery.
+remains exact single-bundle mode and bypasses stack discovery. Wrappers that
+store Relay runtime config elsewhere should set `GHOST_RELAY_CONFIG` or pass
+`ghost relay gather --config <file>`.
 
 ## Legacy Cache Helpers
 

docs/host-adapters.md

@@ -17,10 +17,19 @@ Ghost provides:
 - `ghost review --format json` for advisory packets grounded in the resolved
   fingerprint stack.
 - `ghost relay gather [target] --format json` as the `ghost.relay.gather/v2`
-  contract for generation context, including selected `context_hits`, match
-  reasons, suggested reads, omissions, and gaps.
+  contract for generation context. Host adapters should consume JSON fields
+  such as `context`, `selected_context`, `source`, `targetPaths`, `stackDirs`,
+  gaps, and trace data instead of scraping markdown.
+- `ghost relay gather --request <file> --format json` and
+  `ghost relay gather --request-stdin --format json` for prompt-shaped tasks
+  where the host adapter can provide a structured `ghost.relay-request/v1`.
+- Relay configs as the execution contract for context gathering. Omitted
+  `base` means `base.kind: fingerprint`; explicit `base.kind: none` lets a
+  framework repo gather declared request context without a `.ghost` package.
 - `GHOST_PACKAGE_DIR=<relative-dir>` for wrappers that store Ghost package
   roots somewhere other than `.ghost`.
+- `GHOST_RELAY_CONFIG=<relative-file>` for wrappers that store Relay config
+  somewhere other than `.ghost/relay.yml`.
 
 Host adapters provide:
 
@@ -69,6 +78,59 @@ GHOST_PACKAGE_DIR=.design/memory ghost review --base main --format json
 `--package <dir>` remains exact single-bundle mode. Use it when the caller
 already knows the package root and wants to bypass stack discovery.
 
+## Relay Context Flow
+
+Use JSON as the agent contract:
+
+```bash
+ghost relay gather apps/checkout/review/page.tsx --format json
+```
+
+Relay first loads config by precedence: `--config`, `GHOST_RELAY_CONFIG`,
+discovered `.ghost/relay.yml`, then the built-in default config. Source paths
+inside a Relay config are resolved from the repo root/current working directory,
+not from the config file directory.
+
+When the user prompt is not naturally tied to one repo path, the host adapter
+should create a Relay request from the prompt and pass it to Ghost:
+
+```yaml
+schema: ghost.relay-request/v1
+task: generate-interface
+selectors:
+  customer: merchant
+  brand: square
+  system: managerbot
+  moment: cash-flow-gap
+  medium: push
+  capability: lending
+```
+
+```bash
+ghost relay gather --request-stdin --format json
+```
+
+Framework-owned contexts can keep the same command and provide their runtime
+config explicitly:
+
+```bash
+GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json
+ghost relay gather stacks/managerbot.cash-flow-gap.push.yml --config .agents/ghost/relay.yml --format json
+```
+
+Use `base.kind: none` in that config when there is no base Ghost fingerprint
+package. Ghost will return deterministic gaps such as `no-base-fingerprint`
+instead of throwing a missing `.ghost/manifest.yml` error.
+
+The nested `context.schema` value is `ghost.relay-context/v1`. The top-level
+`brief` field is display text for humans and compatibility. Plain markdown
+output from `ghost relay gather <target>` is a compact human preview and may
+omit projected Relay config sources that are present in JSON.
+
+Ghost resolves request selectors deterministically against declared Relay
+config resolvers. Natural-language extraction belongs to the host adapter, not
+Ghost core.
+
 ## Fingerprint Edits
 
 Adapters do not need a special Ghost draft state. If fingerprint work is