Complete Relay review-gated Project workflow

README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>🚀 Relay-agent</h1>
   <p><strong>Run, monitor, and safely deliver work from Claude Code, Codex CLI, Antigravity, and your own agent CLIs.</strong></p>
-  <p>Desktop GUI · CLI automation · Local daemon · Persistent job history</p>
+  <p>Desktop GUI · CLI automation · Local daemon · Persistent Task Run history</p>
 
   <p>
     <a href="https://github.com/miter37/Relay-agent/actions/workflows/ci.yml"><img src="https://github.com/miter37/Relay-agent/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -12,13 +12,13 @@
   </p>
 </div>
 
-Relay-agent is a local job broker for AI command-line tools. A person can create and inspect jobs in the desktop app, while an automation agent can submit the same work through the CLI. Both paths share one daemon, one SQLite history, and the same validated result-delivery contract.
+Relay-agent is a local work broker for AI command-line tools. A person can create and inspect Task Runs in the desktop app, while an automation agent can submit the same work through the CLI. Both paths share one daemon, one SQLite history, and the same validated result-delivery contract.
 
 <p align="center">
   <img src="docs/assets/relay-agent-gui-main.png" alt="Relay-agent desktop dashboard" width="1200">
 </p>
 
-<p align="center"><em>Monitor Relay health, search and filter job history, and inspect selected work from the desktop dashboard.</em></p>
+<p align="center"><em>Monitor Relay health, search and filter Task Run history, and inspect selected work from the desktop dashboard.</em></p>
 
 > **Reliability boundary:** Relay-agent validates process completion, result-file creation, encoding, schema, artifact paths, and delivery. It does not verify the factual accuracy or reasoning quality of AI-generated content.
 
@@ -40,16 +40,16 @@ Relay-agent is a local job broker for AI command-line tools. A person can create
 
 Relay-agent adds a durable control and delivery layer around powerful AI CLIs.
 
-- **Desktop task control:** Create jobs with task text or a Markdown file, local attachments or delivered files selected by Job ID, Agent and model selection, profiles, fallback behavior, time limits, result paths, and artifact folders.
-- **One shared job history:** GUI, CLI, and external-agent jobs appear in the same searchable history with status, source, timestamps, attempts, and output locations.
+- **Desktop task control:** Create Task Runs with task text or a Markdown file, local attachments or delivered files selected by Task Run ID, Agent and model selection, profiles, fallback behavior, time limits, result paths, and artifact folders.
+- **One shared Task Run history:** GUI, CLI, and external-agent work appears in the same searchable history with status, source, timestamps, Attempts, and output locations.
 - **Detailed inspection:** Review Overview, Task, Progress, Answer, Result, Files, Logs, and Events without digging through Relay's internal database or workspaces.
 - **Non-interrupting progress checks:** Inspect process state, recent activity, stalls, and common error signals without sending another message to the running Agent.
-- **Useful job controls:** Stop active work, run completed work again, copy task text, and open result or artifact folders.
+- **Useful Task Run controls:** Stop active work, run completed work again, copy task text, and open result or Artifact folders.
 - **Built-in and custom Agents:** Use Claude Code, Codex CLI, and Antigravity, or register manifest-backed Agent Apps for other local CLIs.
 - **Safe working-folder delivery:** Let an Agent work on an isolated copy, validate the changed-file set, then apply only those changes to a requested real folder.
-- **Persistent receipts:** Store job metadata, attempts, failures, and output paths in local SQLite history.
+- **Persistent receipts:** Store Task Run metadata, Attempts, failures, and output paths in local SQLite history.
 - **Compatibility safety:** GUI write actions are disabled if the desktop app and daemon do not agree on the supported API or Relay Home.
-- **Automation-ready:** Submit background jobs, deduplicate external requests, wait for completion, and consume machine-readable receipts.
+- **Automation-ready:** Submit background Task Runs, deduplicate external requests, wait for completion, and consume machine-readable receipts.
 
 ## Requirements
 
@@ -94,7 +94,7 @@ The GUI connects to the local Relay daemon and starts it automatically by defaul
 
 ### If the GUI opens in compatibility mode
 
-Compatibility mode protects the job database and disables write actions when the running daemon is older, newer, or using a different Relay Home. Restart the daemon with the same Relay installation:
+Compatibility mode protects the history database and disables write actions when the running daemon is older, newer, or using a different Relay Home. Restart the daemon with the same Relay installation:
 
 ```sh
 relay daemon stop
@@ -145,7 +145,7 @@ Select **+ New Task** and provide as much or as little configuration as needed:
 
 - optional task name
 - inline task text or a UTF-8 task file
-- local attachments, or result and artifact files selected from a completed Job ID
+- local attachments, or result and artifact files selected from a completed Task Run ID
 - Agent and model
 - execution profile
 - fallback preference
@@ -161,13 +161,13 @@ Select **+ New Task** and provide as much or as little configuration as needed:
 
 <p align="center"><em>The New Task form exposes the same Agent, model, fallback, file, result, and working-folder controls available through the CLI.</em></p>
 
-Use **+ Add from Job ID** under **Files** to reuse work from an earlier Job. Relay shows the result and delivered
+Use **+ Add from Task Run ID** under **Files** to reuse work from an earlier Task Run. Relay shows the result and delivered
 artifacts that still exist on disk; select one or more and they become ordinary attachments to the new task. This
-does not create a dependency on running or queued work, so the source Job must have already delivered its files.
+does not create a dependency on running or queued work, so the source Task Run must have already delivered its files.
 
-### 2. Observe the job
+### 2. Observe the Task Run
 
-The job detail view separates the most useful information:
+The Task Run detail view separates the most useful information:
 
 - **Overview:** status, Agent, model, timestamps, source, output locations, and actions
 - **Task:** the submitted instruction
@@ -178,15 +178,15 @@ The job detail view separates the most useful information:
 - **Logs:** stdout, stderr, progress-check results, and attempt selection
 - **Events:** lifecycle history
 
-Use **Check progress** when a running job appears quiet. Relay inspects the process and its recent activity without messaging or interrupting the Agent.
+Use **Check progress** when a running Task Run appears quiet. Relay inspects the process and its recent activity without messaging or interrupting the Agent.
 
 ### 3. Recover or repeat work
 
-Active jobs can be stopped. Completed replayable jobs can be run again, and output folders can be opened directly from the desktop app. Search and filters make older work easier to find by task text, name, Agent, status, source, or time.
+Active Task Runs can be stopped. Completed replayable Task Runs can be run again, and output folders can be opened directly from the desktop app. Search and filters make older work easier to find by task text, name, Agent, status, source, or time.
 
 ## CLI workflow
 
-The desktop app is optional. Every ordinary job can be submitted and inspected from a terminal.
+The desktop app is optional. Every ordinary Task Run can be submitted and inspected from a terminal.
 
 ### Synchronous task
 
@@ -218,14 +218,14 @@ relay submit \
   --machine
 ```
 
-Then use the returned `job_id`:
+Then use the returned Task Run ID:
 
 ```sh
-relay wait <job_id> --machine
-relay result <job_id> --machine
+relay wait <task_run_id> --machine
+relay result <task_run_id> --machine
 ```
 
-`request_id` is an idempotency key for one logical external request. Reusing it returns the existing job even if a local task file has changed. Use a unique value such as `<conversation>-<task>-<agent>`.
+`request_id` is an idempotency key for one logical external request. Reusing it returns the existing Task Run even if a local task file has changed. Use a unique value such as `<conversation>-<task>-<agent>`.
 
 ## Safe work in a real folder
 
@@ -287,7 +287,7 @@ Run `relay add-agent --help` and `relay agent-app --help` for the complete comma
 
 Register `skills/hermes-relay/SKILL.md` (skill name: `use_relay_agent`) in the calling environment. An always-on agent can then submit long-running work to one or more worker CLIs and collect the final receipts asynchronously.
 
-For independent multi-Agent comparison, submit one job per Agent with a unique request ID and `--no-fallback`:
+For independent multi-Agent comparison, submit one Task Run per Agent with a unique request ID and `--no-fallback`:
 
 ```sh
 relay submit --task-file task.md --worker claude --request-id arch-claude --caller hermes --no-fallback --machine
@@ -297,6 +297,32 @@ relay submit --task-file task.md --worker antigravity --request-id arch-antigrav
 
 For unattended execution, configure Relay under a dedicated low-privilege account with explicit filesystem allowlists and ACL isolation.
 
+### Agent-driven Task discovery
+
+Agents should inspect the bounded catalog before submitting new work. Relay provides metadata and stable IDs; the Agent chooses and compares candidates.
+
+```sh
+relay catalog tasks --machine
+relay task show <TASK_ID> --machine
+relay catalog task-runs --status completed --machine
+relay result <TASK_RUN_ID> --machine
+relay artifact show <ARTIFACT_UID> --machine
+relay artifact lineage <ARTIFACT_UID> --machine
+relay catalog projects --machine
+relay project show <PROJECT_ID> --machine
+relay catalog project-runs --status completed --machine
+relay project-run show <PROJECT_RUN_ID> --machine
+```
+
+Use `task_summary`, `result_summary`, and `failure_reason` to narrow candidates, then read the selected Task definition or receipt. Reuse prior output by Artifact UID, not by an arbitrary file path:
+
+```sh
+relay run "Update the previous report" --input-artifact <ARTIFACT_UID>=A1 --machine
+relay run-lineage <TASK_RUN_ID> --machine
+```
+
+Relay does not rank or recommend candidates. Existing `relay search --kind runs|artifacts` remains available for explicit full-text or Artifact searches.
+
 ## Results, security, and operations
 
 ### JSON result contract