From a3702d2934126c4c34eb74cfd139d1d8dff6ddc8 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Fri, 17 Apr 2026 17:41:22 -0400
Subject: [PATCH 01/13] feat(registry): add workflow registry system, replace
 init/templates

Introduce a configurable named-registry system for distributing and
running shared workflows. Registries can be GitHub repos or local
directories, configured once in ~/.conductor/registries.toml and
referenced by short name.

- Add src/conductor/registry/ package (config, resolver, index, cache,
  github helpers, errors)
- Add `conductor registry` CLI subcommand group (list, add, remove,
  set-default, update, show)
- Modify run/resume/validate to accept registry refs
  (name[@registry][@version]) in addition to local file paths
- Remove init/templates feature (init.py, templates/, test_init.py)
- Add httpx dependency for GitHub API fetching
- Add 133 new tests (unit + integration + CLI)
- Update README, cli-reference, design doc, and conductor skill

Supersedes PR #88.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .claude/skills/conductor/SKILL.md             |   6 +-
 .../skills/conductor/references/execution.md  |  43 +-
 README.md                                     |  26 +-
 docs/cli-reference.md                         |  84 ++--
 docs/design/registry.md                       | 280 +++++++++++
 pyproject.toml                                |   1 +
 src/conductor/cli/app.py                      | 183 ++++---
 src/conductor/cli/init.py                     | 171 -------
 src/conductor/cli/registry.py                 | 230 +++++++++
 src/conductor/registry/__init__.py            |   3 +
 src/conductor/registry/cache.py               | 270 ++++++++++
 src/conductor/registry/config.py              | 256 ++++++++++
 src/conductor/registry/errors.py              |  13 +
 src/conductor/registry/github.py              | 176 +++++++
 src/conductor/registry/index.py               | 248 +++++++++
 src/conductor/registry/resolver.py            | 129 +++++
 src/conductor/templates/human-gate.yaml       |  49 --
 src/conductor/templates/loop.yaml             |  51 --
 src/conductor/templates/simple.yaml           |  22 -
 tests/test_cli/test_init.py                   | 255 ----------
 tests/test_cli/test_registry_commands.py      | 258 ++++++++++
 tests/test_registry/__init__.py               |   0
 tests/test_registry/test_cache.py             | 362 ++++++++++++++
 tests/test_registry/test_config.py            | 279 +++++++++++
 tests/test_registry/test_github.py            | 168 +++++++
 tests/test_registry/test_index.py             | 328 ++++++++++++
 tests/test_registry/test_integration.py       | 469 ++++++++++++++++++
 tests/test_registry/test_resolver.py          | 216 ++++++++
 uv.lock                                       |   2 +
 29 files changed, 3861 insertions(+), 717 deletions(-)
 create mode 100644 docs/design/registry.md
 delete mode 100644 src/conductor/cli/init.py
 create mode 100644 src/conductor/cli/registry.py
 create mode 100644 src/conductor/registry/__init__.py
 create mode 100644 src/conductor/registry/cache.py
 create mode 100644 src/conductor/registry/config.py
 create mode 100644 src/conductor/registry/errors.py
 create mode 100644 src/conductor/registry/github.py
 create mode 100644 src/conductor/registry/index.py
 create mode 100644 src/conductor/registry/resolver.py
 delete mode 100644 src/conductor/templates/human-gate.yaml
 delete mode 100644 src/conductor/templates/loop.yaml
 delete mode 100644 src/conductor/templates/simple.yaml
 delete mode 100644 tests/test_cli/test_init.py
 create mode 100644 tests/test_cli/test_registry_commands.py
 create mode 100644 tests/test_registry/__init__.py
 create mode 100644 tests/test_registry/test_cache.py
 create mode 100644 tests/test_registry/test_config.py
 create mode 100644 tests/test_registry/test_github.py
 create mode 100644 tests/test_registry/test_index.py
 create mode 100644 tests/test_registry/test_integration.py
 create mode 100644 tests/test_registry/test_resolver.py

diff --git a/.claude/skills/conductor/SKILL.md b/.claude/skills/conductor/SKILL.md
index fb71f5b..c54094f 100644
--- a/.claude/skills/conductor/SKILL.md
+++ b/.claude/skills/conductor/SKILL.md
@@ -30,8 +30,9 @@ conductor run workflow.yaml --log-file auto               # Log full debug outpu
 conductor run workflow.yaml --web --input q="Hello"       # Real-time web dashboard
 conductor run workflow.yaml --web-bg --input q="Hello"    # Background mode (prints URL, exits)
 conductor validate workflow.yaml                         # Validate only
-conductor init my-workflow --template simple              # Create from template
-conductor templates                                      # List templates
+conductor registry add official myorg/workflows --default # Add a registry
+conductor registry list official                          # List registry workflows
+conductor run qa-bot@official@1.0.0 --input q="Hello"    # Run from registry
 conductor stop                                           # Stop background workflow
 conductor update                                         # Check for and install latest version
 conductor resume workflow.yaml                           # Resume from last checkpoint
@@ -102,5 +103,6 @@ For runtime config, context modes, limits, and cost tracking, see [references/au
 | `runtime` | Provider, model, temperature, max_tokens, MCP servers |
 | `--web` | Real-time web dashboard with DAG graph, live streaming, in-browser human gates |
 | `checkpoint` | Auto-saved on failure; resume with `conductor resume` |
+| `registry` | Named workflow sources (GitHub repo or local dir) for sharing workflows |
 
 For pattern examples (linear, loop, conditional, parallel, for-each, human gate) and template syntax, see [references/authoring.md](references/authoring.md).
diff --git a/.claude/skills/conductor/references/execution.md b/.claude/skills/conductor/references/execution.md
index 6db4034..4afa5cd 100644
--- a/.claude/skills/conductor/references/execution.md
+++ b/.claude/skills/conductor/references/execution.md
@@ -195,40 +195,45 @@ Checks:
 - Parallel group agent references
 - For-each source format and reserved names
 
-### conductor init
+### conductor registry
 
-Create workflow from template:
+Manage workflow registries — named sources of shared workflows (GitHub repos or local directories).
 
 ```bash
-conductor init <name> [OPTIONS]
+conductor registry <subcommand> [OPTIONS]
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--template`, `-t TEMPLATE` | Template to use (default: simple) |
-| `--output`, `-o PATH` | Output file path |
+| Subcommand | Description |
+|------------|-------------|
+| `list [name]` | List registries, or workflows in a specific registry |
+| `add <name> <source>` | Add a registry (`--type github\|path`, `--default`) |
+| `remove <name>` | Remove a registry |
+| `set-default <name>` | Set the default registry |
+| `update [name]` | Refresh index and re-resolve latest versions |
+| `show <ref>` | Show metadata for a workflow reference |
 
 **Examples:**
 
 ```bash
-conductor init my-workflow
-conductor init my-workflow --template loop
-conductor init review -t human-gate -o ./workflows/review.yaml
+conductor registry add official myorg/conductor-workflows --default
+conductor registry add local /path/to/workflows --type path
+conductor registry list                        # show configured registries
+conductor registry list official               # show workflows in a registry
+conductor registry set-default official
+conductor registry update                      # refresh all indexes
+conductor registry show qa-bot@official@1.0.0  # show workflow metadata
 ```
 
-### conductor templates
-
-List available templates:
+**Running from a registry:**
 
 ```bash
-conductor templates
+conductor run qa-bot                     # latest from default registry
+conductor run qa-bot@official            # latest from named registry
+conductor run qa-bot@official@1.2.3      # explicit version
+conductor run qa-bot@@1.2.3              # explicit version from default registry
 ```
 
-| Template | Description |
-|----------|-------------|
-| `simple` | Single agent with basic I/O |
-| `loop` | Iterative refinement pattern |
-| `human-gate` | Workflow with approval gate |
+Registry workflows are cached locally at `~/.conductor/cache/registries/` and reused on subsequent runs. Explicit versions are immutable; `latest` is re-resolved on `conductor registry update`.
 
 ## Execution Flow
 
diff --git a/README.md b/README.md
index b7d4deb..97d430a 100644
--- a/README.md
+++ b/README.md
@@ -207,23 +207,29 @@ Validate a workflow file without executing.
 conductor validate <workflow.yaml>
 ```
 
-### `conductor init`
-
-Create a new workflow from a template.
+**Full CLI documentation:** [docs/cli-reference.md](docs/cli-reference.md)
 
-```bash
-conductor init <name> --template <template> --output <path>
-```
+## Workflow Registries
 
-### `conductor templates`
+Conductor supports named workflow registries — GitHub repos or local directories
+containing shared workflows. Configure a registry once, then run workflows by
+short name.
 
-List available workflow templates.
+### Quick start
 
 ```bash
-conductor templates
+# Add a registry
+conductor registry add official myorg/conductor-workflows --default
+
+# List available workflows
+conductor registry list official
+
+# Run a workflow from the registry
+conductor run qa-bot                    # latest from default registry
+conductor run qa-bot@official@1.2.3    # specific version
 ```
 
-**Full CLI documentation:** [docs/cli-reference.md](docs/cli-reference.md)
+See [docs/design/registry.md](docs/design/registry.md) for the full design.
 
 ## Examples
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 8646ea7..238deee 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -7,8 +7,7 @@ Complete command-line reference for Conductor.
 - [`conductor run`](#conductor-run)
 - [`conductor stop`](#conductor-stop)
 - [`conductor validate`](#conductor-validate)
-- [`conductor init`](#conductor-init)
-- [`conductor templates`](#conductor-templates)
+- [`conductor registry`](#conductor-registry)
 
 ## `conductor run`
 
@@ -190,68 +189,75 @@ for f in examples/*.yaml; do conductor validate "$f"; done
 - Circular dependency detection
 - Input/output schema validation
 
-## `conductor init`
+## `conductor registry`
 
-Create a new workflow file from a template.
+Manage workflow registries — named sources (GitHub repos or local directories) for shared workflows.
 
 ```bash
-conductor init <name> [OPTIONS]
+conductor registry <subcommand> [OPTIONS]
 ```
 
+### Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list [NAME]` | List registries, or list workflows in a specific registry |
+| `add <NAME> <SOURCE>` | Add a new registry (GitHub `owner/repo` or local path) |
+| `remove <NAME>` | Remove a registry |
+| `set-default <NAME>` | Set the default registry |
+| `update [NAME]` | Update cached registry index (all or specific) |
+| `show <NAME>` | Show registry details and status |
+
 ### Options
 
-| Option | Short | Description |
-|--------|-------|-------------|
-| `--template TEMPLATE` | `-t` | Template to use (default: simple) |
-| `--output PATH` | `-o` | Output file path |
+| Option | Description |
+|--------|-------------|
+| `--default` | Mark as the default registry (with `add`) |
 
 ### Examples
 
 ```bash
-# Create a simple workflow (default template)
-conductor init my-workflow
+# Add a GitHub-hosted registry and set it as default
+conductor registry add official myorg/conductor-workflows --default
 
-# Create from a specific template
-conductor init my-workflow --template loop
+# Add a local directory registry
+conductor registry add local ./my-workflows
 
-# Specify output path
-conductor init my-workflow -t human-gate -o ./workflows/review.yaml
+# List all configured registries
+conductor registry list
 
-# Create a parallel workflow
-conductor init research --template parallel -o research.yaml
-```
+# List workflows in a specific registry
+conductor registry list official
+
+# Show registry details
+conductor registry show official
 
-### Available Templates
+# Set a different default
+conductor registry set-default local
 
-Use `conductor templates` to see the full list. Common templates:
+# Update cached registry index
+conductor registry update
 
-- `simple` - Single agent, basic Q&A (default)
-- `loop` - Agent with loop-back pattern
-- `parallel` - Static parallel execution
-- `human-gate` - Workflow with human approval gate
-- `for-each` - Dynamic parallel processing
+# Remove a registry
+conductor registry remove local
+```
 
-## `conductor templates`
+### Running Workflows from a Registry
 
-List available workflow templates with descriptions.
+Once a registry is configured, `conductor run` accepts short workflow names:
 
 ```bash
-conductor templates
-```
+# Run from default registry (latest version)
+conductor run qa-bot
 
-### Example Output
+# Run from a specific registry
+conductor run qa-bot@official
 
+# Run a specific version
+conductor run qa-bot@official@1.2.3
 ```
-Available templates:
-
-  simple      Single agent workflow for basic Q&A
-  loop        Agent with conditional loop-back
-  parallel    Static parallel agent execution
-  human-gate  Workflow with human approval gate
-  for-each    Dynamic parallel (for-each) processing
 
-Use: conductor init <name> --template <template>
-```
+See [design/registry.md](./design/registry.md) for the full design.
 
 ## Environment Variables
 
diff --git a/docs/design/registry.md b/docs/design/registry.md
new file mode 100644
index 0000000..614af58
--- /dev/null
+++ b/docs/design/registry.md
@@ -0,0 +1,280 @@
+# Workflow Registry
+
+Status: **Proposed**
+Supersedes: PR #88 (workflow template registry)
+
+## Summary
+
+Introduce a configurable, named **registry** system for distributing and
+running shared workflows. A registry is either a GitHub repository or a local
+directory, configured once and referenced by short name. Workflows can be run
+directly from a registry by reference, with explicit versioning and local
+caching. Replaces the existing local templates / `init` scaffolding feature
+entirely.
+
+## Motivation
+
+Today, Conductor ships a small set of bundled YAML templates (`simple`,
+`loop`, `human-gate`) accessed via `conductor init` and `conductor templates`.
+PR #88 attempted to extend this with a hardcoded "remote template registry"
+pointing at `microsoft/conductor-workflows`. That approach has several
+problems:
+
+- Mixes two concerns — initial scaffolding for new users vs. distribution of
+  reusable workflows — into one feature.
+- Hardcodes a single remote source.
+- No versioning, no caching, fetched on every invocation.
+- Uses naive string substitution instead of the existing Jinja2 path,
+  inconsistent with how local workflows are loaded.
+- The bundled templates feature itself is small and rarely the right
+  starting point for real workflows; teams want to share their own workflows.
+
+A proper registry mechanism replaces both, gives teams a way to share
+workflows across repos and machines, and removes a maintenance burden.
+
+## Goals
+
+- Run a workflow from a remote source by short name and explicit version.
+- Configure multiple named registries (org-wide official, team-internal,
+  personal local dir) and switch between them with no command-line ceremony.
+- Reproducible runs: a versioned reference resolves to the same workflow
+  bytes every time.
+- Preserve all existing local-file behavior — bare paths still work
+  unchanged.
+- Keep the registry mechanism out of the engine: it is a CLI/loader concern.
+
+## Non-goals (v1)
+
+- SemVer ranges (`^1.0`, `~1.2`). Exact-version matching only.
+- Authenticated fetches for private GitHub repos. Public repos only in v1.
+- Server-side validation, signing, or attestation of registry contents.
+- A `conductor publish` command. Publishing is just `git push` + tag.
+- A central, blessed registry maintained by the Conductor project. Users
+  configure their own.
+
+## User experience
+
+### Registry configuration
+
+Stored at `~/.conductor/registries.toml`:
+
+```toml
+default = "official"
+
+[registries.official]
+type = "github"
+source = "myorg/conductor-workflows"
+
+[registries.team]
+type = "github"
+source = "myorg/team-workflows"
+
+[registries.local]
+type = "path"
+source = "/Users/jason/workflows"
+```
+
+Managed via:
+
+```
+conductor registry add <name> <source> [--type github|path] [--default]
+conductor registry remove <name>
+conductor registry set-default <name>
+conductor registry list                  # list configured registries
+conductor registry list <name>           # list workflows in a registry
+conductor registry update [<name>]       # refresh index + re-resolve `latest`
+conductor registry show <ref>            # show metadata + cached path
+```
+
+The `type` flag is optional; `add` infers `github` if `<source>` matches
+`owner/repo`, otherwise `path`.
+
+### Reference syntax
+
+```
+<workflow>[@<registry>][@<version>]
+```
+
+Resolution rules, in order:
+
+1. If the argument exists as a file on disk, treat it as a local path.
+2. Otherwise parse as a registry reference.
+3. Missing `@<registry>` → use the configured default registry.
+4. Missing `@<version>` → use `latest` (highest version listed in the
+   registry index).
+
+Examples:
+
+```
+conductor run ./my-workflow.yaml          # local file (unchanged)
+conductor run qa-bot                      # latest from default registry
+conductor run qa-bot@team                 # latest from `team` registry
+conductor run qa-bot@team@1.2.3           # exact version from `team`
+conductor run qa-bot@@1.2.3               # exact version from default registry
+```
+
+### Registry index
+
+Each registry root must contain `index.yaml` (preferred) or `index.json`:
+
+```yaml
+workflows:
+  qa-bot:
+    description: "Simple Q&A workflow"
+    path: workflows/qa-bot.yaml          # path relative to registry root
+    versions: ["1.0.0", "1.1.0", "2.0.0"]
+  code-review:
+    description: "Multi-agent code review"
+    path: workflows/code-review.yaml
+    versions: ["0.3.0"]
+```
+
+For GitHub registries, versions correspond to git tags on the registry repo.
+For local registries, the maintainer maintains the version list directly.
+
+The index is the single source of truth for what workflows exist and what
+versions are available. Conductor does not auto-discover YAML files in a
+registry — the maintainer curates the index.
+
+### Caching
+
+Fetched workflows are cached at:
+
+```
+~/.conductor/cache/registries/<registry>/<workflow>/<version>/
+```
+
+- Cache is keyed by `(registry, workflow, version)`.
+- Explicit versions are immutable: once cached, never re-fetched.
+- `latest` is re-resolved on `conductor registry update`. Each resolved
+  version is cached in its own directory.
+- Index files are cached separately at
+  `~/.conductor/cache/registries/<registry>/index.<yaml|json>` and refreshed
+  on `update`.
+
+This produces a stable on-disk path for every registry-fetched workflow,
+which is required by:
+
+- The YAML loader's `!file` tag, which resolves relative to the workflow file.
+- The checkpoint system, which derives checkpoint identity from
+  `workflow_path.stem`.
+
+### Workflow assets
+
+Workflows can reference sibling files (prompts, JSON schemas, scripts) via
+relative paths or `!file`. The cache layer fetches the workflow YAML **plus
+all sibling files in its containing directory** as part of a single fetch
+operation. Registry maintainers should keep a workflow and its assets in the
+same directory.
+
+For GitHub registries, sibling fetch uses the Git Trees API to enumerate the
+directory and `raw.githubusercontent.com` to download files at the pinned
+ref (tag).
+
+### Run / resume / validate
+
+These commands accept either a local path or a registry reference:
+
+```
+conductor run qa-bot@team@1.2.3 --input question="What is X?"
+conductor resume qa-bot@team@1.2.3
+conductor validate qa-bot@team@1.2.3
+```
+
+The resolver runs first, returns a concrete `Path` to the cached file, and
+the rest of the pipeline is unchanged.
+
+## Removed in this design
+
+- `conductor init` and the entire `src/conductor/cli/init.py` module.
+- `conductor templates` command.
+- `src/conductor/templates/` directory and its bundled YAML templates.
+- `tests/test_cli/test_init.py`.
+- All references in README and docs.
+
+This is a breaking change for anyone using `init` or `templates`. Both are
+recent, undocumented in many places, and supersede-able by a 5-line
+`curl | tee` or by configuring the new registry.
+
+## Implementation
+
+### New package: `src/conductor/registry/`
+
+| Module      | Responsibility                                                                                                                                                                                                       |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config.py` | Pydantic models for `registries.toml`. Atomic load/save. Handles missing-file case (returns empty config).                                                                                                            |
+| `resolver.py` | Parses `name[@registry][@version]`. Decides file-vs-ref. Returns a `ResolvedRef` with registry name, workflow name, version, and the registry config.                                                                |
+| `index.py`  | Loads and parses `index.yaml`/`index.json`. Validates structure. Resolves `latest` to a concrete version. Backed by either the local FS or `github.py`.                                                               |
+| `cache.py`  | Manages `~/.conductor/cache/registries/`. `get_or_fetch(ref) -> Path`. Idempotent. Fetches sibling files. Knows when to refetch (`latest`) vs. reuse (explicit version).                                              |
+| `github.py` | Public-only GitHub helpers: fetch a file at a ref via raw URL, list tags via the REST API for `latest`, list directory contents via Git Trees API for sibling enumeration. Uses `httpx`, no auth.                    |
+
+### CLI: `src/conductor/cli/registry.py`
+
+Implements the `conductor registry` Typer subcommand group. Replaces PR #88's
+file of the same name.
+
+### Modifications
+
+- `src/conductor/cli/app.py`
+  - Register the `registry` subcommand group.
+  - Remove `init` and `templates` commands and their imports.
+  - In `run`, `resume`, `validate`: pre-process the workflow argument through
+    the resolver to produce a `Path`.
+- `src/conductor/cli/run.py` — accept resolved `Path`, no other change.
+
+### Tests
+
+- `tests/test_registry/` — unit tests for `config`, `resolver`, `index`,
+  `cache`, `github` (with `httpx` mocked).
+- `tests/test_cli/test_registry_commands.py` — CLI surface tests using
+  Typer's `CliRunner`.
+- `tests/test_cli/test_app.py` — drop assertions about `init` / `templates`.
+- Delete `tests/test_cli/test_init.py`.
+
+### Docs
+
+- `README.md` — remove templates section, add a brief registry section with
+  link to this doc.
+- `docs/cli-reference.md` — add `registry` subcommand reference, drop
+  `init` / `templates`.
+- New `docs/registry.md` (user-facing guide; this doc is the design rationale).
+
+## Design decisions and rationale
+
+| Decision                                  | Choice                                                  | Why                                                                                                  |
+| ----------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Named registries vs always-inline source  | Named, configured once                                  | Mirrors npm/cargo. Short refs in `run` commands. Default registry makes the common case zero-config. |
+| Versioning                                | Explicit, npm-style                                     | Reproducibility. Lockfile-friendly later. Matches existing GitHub tag conventions.                   |
+| Local-registry layout                     | Directory + `index.yaml`                                | Consistent with GitHub registries. Maintainer controls what's exposed and at what versions.          |
+| Caching strategy                          | Local cache, refresh on `registry update` or new version | Avoids per-run network. Stable on-disk paths needed for `!file` and checkpoints.                     |
+| Reference syntax                          | `name@registry@version`                                 | Visually unambiguous. `@` parses cleanly. Supports either-or-both omissions.                         |
+| Publish / publish validation              | Dropped                                                 | Distribution is `git push` + tag. Validation belongs in user CI, not the CLI.                        |
+| Authenticated/private registries          | Out of scope v1                                         | Public raw URLs cover the common case. Token support can come later via a registry config field.    |
+| SemVer ranges                             | Out of scope v1                                         | Adds resolver complexity for marginal benefit until ecosystems exist.                                |
+| Index format                              | YAML primary, JSON fallback                             | Consistent with workflow files. JSON tolerated for tooling.                                          |
+
+## Open questions
+
+- **Sibling fetch scope for GitHub.** Should we fetch only files in the
+  workflow's immediate directory, or recurse? Proposal: immediate directory
+  only in v1. Workflows that need deeper assets can flatten their layout.
+- **Cache size management.** Unbounded cache growth is fine for v1 (workflows
+  are small text). A `conductor registry prune` command can come later.
+- **Empty default registry.** Ship with no default configured. The first
+  `conductor registry add ... --default` sets it. Avoids hardcoding a repo
+  that may not exist or that the project doesn't want to bless.
+
+## Migration
+
+PR #88 is unmerged. There is no existing registry feature on `main` to
+migrate. The `init` / `templates` removal is technically a breaking change
+but those commands are recent and trivially replaced by users copying any
+example YAML.
+
+## Future work
+
+- SemVer range matching.
+- Authenticated GitHub fetch (token in config or via `gh auth token`).
+- Other sources (HTTPS tarball, OCI artifacts).
+- A lockfile (`conductor.lock`) capturing exact versions used by a project.
+- Signed indexes or workflow content for trusted distribution.
diff --git a/pyproject.toml b/pyproject.toml
index d48e20f..7d028b4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -43,6 +43,7 @@ dependencies = [
     "fastapi>=0.115.0",
     "uvicorn>=0.30.0",
     "websockets>=12.0",
+    "httpx>=0.27.0",
 ]
 
 [project.urls]
diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py
index 07c316d..9f53c73 100644
--- a/src/conductor/cli/app.py
+++ b/src/conductor/cli/app.py
@@ -35,6 +35,11 @@ class ConsoleVerbosity(str, Enum):
     no_args_is_help=True,
 )
 
+# Register subcommand groups
+from conductor.cli.registry import registry_app  # noqa: E402
+
+app.add_typer(registry_app)
+
 # Rich console for formatted output
 console = Console(stderr=True)
 output_console = Console()
@@ -212,14 +217,9 @@ def main(
 @app.command()
 def run(
     workflow: Annotated[
-        Path,
+        str,
         typer.Argument(
-            help="Path to the workflow YAML file.",
-            exists=True,
-            file_okay=True,
-            dir_okay=False,
-            readable=True,
-            resolve_path=True,
+            help="Workflow file path or registry reference (name[@registry][@version]).",
         ),
     ],
     provider: Annotated[
@@ -320,6 +320,25 @@ def run(
     import asyncio
     import json
 
+    from conductor.registry.cache import fetch_workflow as fetch_registry_workflow
+    from conductor.registry.errors import RegistryError
+    from conductor.registry.resolver import resolve_ref
+
+    try:
+        ref = resolve_ref(workflow)
+        if ref.kind == "file":
+            workflow_path = ref.path
+        else:
+            workflow_path = fetch_registry_workflow(
+                registry_name=ref.registry_name,
+                registry_entry=ref.registry_entry,
+                workflow_name=ref.workflow,
+                version=ref.version,
+            )
+    except RegistryError as e:
+        print_error(e)
+        raise typer.Exit(code=1) from None
+
     # Import here to avoid circular imports and defer heavy imports
     from conductor.cli.run import (
         InputCollector,
@@ -333,7 +352,7 @@ def run(
     # Handle dry-run mode
     if dry_run:
         try:
-            plan = build_dry_run_plan(workflow)
+            plan = build_dry_run_plan(workflow_path)
             display_execution_plan(plan, output_console)
             return
         except Exception as e:
@@ -358,7 +377,7 @@ def run(
     resolved_log_file: Path | None = None
     if log_file is not None:
         if log_file.lower() == "auto":
-            resolved_log_file = generate_log_path(workflow.stem)
+            resolved_log_file = generate_log_path(workflow_path.stem)
         else:
             resolved_log_file = Path(log_file)
 
@@ -368,7 +387,7 @@ def run(
 
         try:
             url = launch_background(
-                workflow_path=workflow,
+                workflow_path=workflow_path,
                 inputs=inputs,
                 provider_override=provider,
                 skip_gates=skip_gates,
@@ -390,7 +409,7 @@ def run(
         # Run the workflow
         result = asyncio.run(
             run_workflow_async(
-                workflow,
+                workflow_path,
                 inputs,
                 provider,
                 skip_gates,
@@ -413,14 +432,9 @@ def run(
 @app.command()
 def validate(
     workflow: Annotated[
-        Path,
+        str,
         typer.Argument(
-            help="Path to the workflow YAML file to validate.",
-            exists=True,
-            file_okay=True,
-            dir_okay=False,
-            readable=True,
-            resolve_path=True,
+            help="Workflow file path or registry reference (name[@registry][@version]).",
         ),
     ],
 ) -> None:
@@ -436,97 +450,49 @@ def validate(
     Examples:
         conductor validate workflow.yaml
         conductor validate ./examples/my-workflow.yaml
+        conductor validate qa-bot@team@1.0.0
     """
+    from conductor.registry.cache import fetch_workflow as fetch_registry_workflow
+    from conductor.registry.errors import RegistryError
+    from conductor.registry.resolver import resolve_ref
+
+    try:
+        ref = resolve_ref(workflow)
+        if ref.kind == "file":
+            workflow_path = ref.path
+        else:
+            workflow_path = fetch_registry_workflow(
+                registry_name=ref.registry_name,
+                registry_entry=ref.registry_entry,
+                workflow_name=ref.workflow,
+                version=ref.version,
+            )
+    except RegistryError as e:
+        print_error(e)
+        raise typer.Exit(code=1) from None
+
     from conductor.cli.validate import (
         display_validation_success,
         validate_workflow,
     )
 
-    is_valid, config = validate_workflow(workflow, output_console)
+    is_valid, config = validate_workflow(workflow_path, output_console)
 
     if is_valid and config is not None:
-        display_validation_success(config, workflow, output_console)
+        display_validation_success(config, workflow_path, output_console)
     else:
         raise typer.Exit(code=1)
 
 
-@app.command()
-def init(
-    name: Annotated[
-        str,
-        typer.Argument(
-            help="Name for the new workflow.",
-        ),
-    ],
-    template: Annotated[
-        str,
-        typer.Option(
-            "--template",
-            "-t",
-            help="Template to use (see 'conductor templates' for options).",
-        ),
-    ] = "simple",
-    output: Annotated[
-        Path | None,
-        typer.Option(
-            "--output",
-            "-o",
-            help="Output file path. Defaults to <name>.yaml in current directory.",
-        ),
-    ] = None,
-) -> None:
-    """Initialize a new workflow file from a template.
-
-    Creates a new workflow YAML file based on the specified template.
-    Use 'conductor templates' to see available templates.
-
-    \b
-    Examples:
-        conductor init my-workflow
-        conductor init my-workflow --template loop
-        conductor init my-workflow -t human-gate -o ./workflows/my-workflow.yaml
-    """
-    from conductor.cli.init import create_workflow_file, get_template
-
-    # Check if template exists
-    template_info = get_template(template)
-    if template_info is None:
-        console.print(f"[bold red]Error:[/bold red] Template '{template}' not found.")
-        console.print("[dim]Use 'conductor templates' to see available templates.[/dim]")
-        raise typer.Exit(code=1)
-
-    try:
-        create_workflow_file(name, template, output, output_console)
-    except FileExistsError as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
-        console.print("[dim]Use --output to specify a different path.[/dim]")
-        raise typer.Exit(code=1) from None
-    except ValueError as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
-        raise typer.Exit(code=1) from None
-
-
-@app.command()
-def templates() -> None:
-    """List available workflow templates.
-
-    Shows all templates that can be used with 'conductor init'.
-
-    \b
-    Examples:
-        conductor templates
-    """
-    from conductor.cli.init import display_templates
-
-    display_templates(output_console)
-
-
 @app.command()
 def resume(
     workflow: Annotated[
-        Path | None,
+        str | None,
         typer.Argument(
-            help="Path to the workflow YAML file. Finds the latest checkpoint for this workflow.",
+            help=(
+                "Workflow file path or registry reference (name[@registry][@version]). "
+                "Finds the latest checkpoint for this workflow."
+            ),
         ),
     ] = None,
     from_checkpoint: Annotated[
@@ -596,13 +562,32 @@ def resume(
         )
         raise typer.Exit(code=1)
 
-    # Resolve workflow path if provided (Typer doesn't auto-resolve optional args)
+    # Resolve workflow ref if provided
     resolved_workflow: Path | None = None
     if workflow is not None:
-        resolved_workflow = workflow.resolve()
-        if not resolved_workflow.exists():
-            console.print(f"[bold red]Error:[/bold red] Workflow file not found: {workflow}")
-            raise typer.Exit(code=1)
+        from conductor.registry.cache import fetch_workflow as fetch_registry_workflow
+        from conductor.registry.errors import RegistryError
+        from conductor.registry.resolver import resolve_ref
+
+        try:
+            ref = resolve_ref(workflow)
+            if ref.kind == "file":
+                resolved_workflow = ref.path.resolve()
+                if not resolved_workflow.exists():
+                    console.print(
+                        f"[bold red]Error:[/bold red] Workflow file not found: {workflow}"
+                    )
+                    raise typer.Exit(code=1)
+            else:
+                resolved_workflow = fetch_registry_workflow(
+                    registry_name=ref.registry_name,
+                    registry_entry=ref.registry_entry,
+                    workflow_name=ref.workflow,
+                    version=ref.version,
+                )
+        except RegistryError as e:
+            print_error(e)
+            raise typer.Exit(code=1) from None
 
     # Resolve checkpoint path if provided
     resolved_checkpoint: Path | None = None
@@ -618,7 +603,7 @@ def resume(
     resolved_log_file: Path | None = None
     if log_file is not None:
         if log_file.lower() == "auto":
-            name = workflow.stem if workflow else "resume"
+            name = resolved_workflow.stem if resolved_workflow else "resume"
             resolved_log_file = generate_log_path(name)
         else:
             resolved_log_file = Path(log_file)
diff --git a/src/conductor/cli/init.py b/src/conductor/cli/init.py
deleted file mode 100644
index b1fd2ed..0000000
--- a/src/conductor/cli/init.py
+++ /dev/null
@@ -1,171 +0,0 @@
-"""Implementation of the 'conductor init' and 'conductor templates' commands.
-
-This module provides functionality to initialize new workflow files
-from templates and list available templates.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-from rich.console import Console
-from rich.table import Table
-
-
-@dataclass
-class TemplateInfo:
-    """Information about a workflow template."""
-
-    name: str
-    description: str
-    filename: str
-    features: list[str]
-
-
-# Register available templates
-TEMPLATES: dict[str, TemplateInfo] = {
-    "simple": TemplateInfo(
-        name="simple",
-        description="A minimal linear workflow with a single agent",
-        filename="simple.yaml",
-        features=["single agent", "linear flow"],
-    ),
-    "loop": TemplateInfo(
-        name="loop",
-        description="A workflow with loop-back pattern for iterative refinement",
-        filename="loop.yaml",
-        features=["multiple agents", "loop-back", "conditional routing"],
-    ),
-    "human-gate": TemplateInfo(
-        name="human-gate",
-        description="A workflow with human-in-the-loop approval gate",
-        filename="human-gate.yaml",
-        features=["human gate", "interactive", "approval workflow"],
-    ),
-}
-
-
-def get_template_dir() -> Path:
-    """Get the path to the templates directory."""
-    return Path(__file__).parent.parent / "templates"
-
-
-def list_templates() -> list[TemplateInfo]:
-    """Get a list of all available templates.
-
-    Returns:
-        List of TemplateInfo objects for each template.
-    """
-    return list(TEMPLATES.values())
-
-
-def get_template(name: str) -> TemplateInfo | None:
-    """Get a template by name.
-
-    Args:
-        name: The template name.
-
-    Returns:
-        TemplateInfo if found, None otherwise.
-    """
-    return TEMPLATES.get(name)
-
-
-def render_template(template_name: str, workflow_name: str) -> str:
-    """Render a template with the given workflow name.
-
-    Args:
-        template_name: Name of the template to use.
-        workflow_name: Name for the new workflow.
-
-    Returns:
-        The rendered template content.
-
-    Raises:
-        ValueError: If the template is not found.
-    """
-    template_info = get_template(template_name)
-    if template_info is None:
-        raise ValueError(f"Template '{template_name}' not found")
-
-    template_path = get_template_dir() / template_info.filename
-    if not template_path.exists():
-        raise ValueError(f"Template file not found: {template_path}")
-
-    content = template_path.read_text(encoding="utf-8")
-
-    # Simple template substitution (replacing {{ name }} with workflow_name)
-    # We use a simple string replacement to avoid conflicts with Jinja2
-    # syntax that may be in the template
-    content = content.replace("{{ name }}", workflow_name)
-
-    return content
-
-
-def display_templates(console: Console | None = None) -> None:
-    """Display available templates with Rich formatting.
-
-    Args:
-        console: Optional Rich console for output.
-    """
-    output_console = console if console is not None else Console()
-
-    table = Table(title="Available Workflow Templates", show_lines=True)
-    table.add_column("Name", style="cyan", width=12)
-    table.add_column("Description", width=50)
-    table.add_column("Features")
-
-    for template in list_templates():
-        features_str = ", ".join(template.features)
-        table.add_row(template.name, template.description, features_str)
-
-    output_console.print(table)
-    output_console.print()
-    output_console.print(
-        "[dim]Use 'conductor init <workflow-name> --template <name>' "
-        "to create a new workflow from a template.[/dim]"
-    )
-
-
-def create_workflow_file(
-    workflow_name: str,
-    template_name: str = "simple",
-    output_path: Path | None = None,
-    console: Console | None = None,
-) -> Path:
-    """Create a new workflow file from a template.
-
-    Args:
-        workflow_name: Name for the new workflow.
-        template_name: Template to use (default: "simple").
-        output_path: Optional output path. Defaults to <workflow_name>.yaml.
-        console: Optional Rich console for output.
-
-    Returns:
-        Path to the created file.
-
-    Raises:
-        ValueError: If the template is not found.
-        FileExistsError: If the output file already exists.
-    """
-    output_console = console if console is not None else Console()
-
-    # Determine output path
-    if output_path is None:
-        # Sanitize workflow name for filename
-        safe_name = workflow_name.replace(" ", "-").lower()
-        output_path = Path(f"{safe_name}.yaml")
-
-    # Check if file already exists
-    if output_path.exists():
-        raise FileExistsError(f"File already exists: {output_path}")
-
-    # Render and write template
-    content = render_template(template_name, workflow_name)
-    output_path.write_text(content, encoding="utf-8")
-
-    output_console.print(f"[green]Created workflow file:[/green] {output_path}")
-    output_console.print(f"[dim]Template used:[/dim] {template_name}")
-
-    return output_path
diff --git a/src/conductor/cli/registry.py b/src/conductor/cli/registry.py
new file mode 100644
index 0000000..d73b43a
--- /dev/null
+++ b/src/conductor/cli/registry.py
@@ -0,0 +1,230 @@
+"""Typer subcommand group for workflow registry management."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from conductor.registry.cache import clear_cache, get_cached_workflow_path
+from conductor.registry.config import (
+    RegistryType,
+    add_registry,
+    get_registry,
+    load_config,
+    remove_registry,
+    save_config,
+)
+from conductor.registry.errors import RegistryError
+from conductor.registry.index import load_index
+from conductor.registry.resolver import resolve_ref
+
+registry_app = typer.Typer(
+    name="registry",
+    help="Manage workflow registries.",
+    no_args_is_help=True,
+)
+
+console = Console(stderr=True)
+output_console = Console()
+
+
+@registry_app.command("list")
+def list_registries(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="Registry name to list workflows from."),
+    ] = None,
+) -> None:
+    """List configured registries, or workflows in a specific registry."""
+    try:
+        if name is None:
+            _list_all_registries()
+        else:
+            _list_registry_workflows(name)
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+def _list_all_registries() -> None:
+    """Display a table of all configured registries."""
+    config = load_config()
+
+    if not config.registries:
+        output_console.print("No registries configured.")
+        output_console.print("Run [bold]conductor registry add <name> <source>[/bold] to add one.")
+        return
+
+    table = Table(title="Configured Registries")
+    table.add_column("Name", style="cyan")
+    table.add_column("Type", style="green")
+    table.add_column("Source")
+    table.add_column("Default", justify="center")
+
+    for reg_name, entry in config.registries.items():
+        is_default = "✓" if config.default == reg_name else ""
+        table.add_row(reg_name, entry.type.value, entry.source, is_default)
+
+    output_console.print(table)
+
+
+def _list_registry_workflows(name: str) -> None:
+    """Display a table of workflows in a specific registry."""
+    entry = get_registry(name)
+    index = load_index(entry)
+
+    if not index.workflows:
+        output_console.print(f"No workflows found in registry '{name}'.")
+        return
+
+    table = Table(title=f"Workflows in '{name}'")
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+    table.add_column("Versions", style="green")
+
+    for wf_name, info in index.workflows.items():
+        versions = ", ".join(info.versions) if info.versions else "-"
+        table.add_row(wf_name, info.description or "-", versions)
+
+    output_console.print(table)
+
+
+@registry_app.command()
+def add(
+    name: Annotated[str, typer.Argument(help="Name for the registry.")],
+    source: Annotated[
+        str,
+        typer.Argument(help="Registry source (owner/repo for GitHub, path for local)."),
+    ],
+    type: Annotated[
+        str | None,
+        typer.Option("--type", "-t", help="Registry type: github or path."),
+    ] = None,
+    default: Annotated[
+        bool,
+        typer.Option("--default", "-d", help="Set as the default registry."),
+    ] = False,
+) -> None:
+    """Add a new workflow registry."""
+    try:
+        reg_type = RegistryType(type) if type is not None else None
+        add_registry(name, source, registry_type=reg_type, set_default=default)
+        output_console.print(f"Registry '{name}' added ({source}).")
+        if default:
+            output_console.print(f"Set '{name}' as the default registry.")
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+@registry_app.command()
+def remove(
+    name: Annotated[str, typer.Argument(help="Name of the registry to remove.")],
+) -> None:
+    """Remove a workflow registry."""
+    try:
+        remove_registry(name)
+        output_console.print(f"Registry '{name}' removed.")
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+@registry_app.command("set-default")
+def set_default(
+    name: Annotated[str, typer.Argument(help="Name of the registry to set as default.")],
+) -> None:
+    """Set the default workflow registry."""
+    try:
+        config = load_config()
+        if name not in config.registries:
+            raise RegistryError(
+                f"Registry '{name}' not found",
+                suggestion="Run 'conductor registry list' to see available registries.",
+            )
+        config.default = name
+        save_config(config)
+        output_console.print(f"Default registry set to '{name}'.")
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+@registry_app.command()
+def update(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="Registry to update (all if omitted)."),
+    ] = None,
+) -> None:
+    """Refresh registry index and clear cached workflows."""
+    try:
+        config = load_config()
+
+        if name is not None:
+            if name not in config.registries:
+                raise RegistryError(
+                    f"Registry '{name}' not found",
+                    suggestion="Run 'conductor registry list' to see available registries.",
+                )
+            clear_cache(name)
+            load_index(config.registries[name])
+            output_console.print(f"Registry '{name}' updated.")
+        else:
+            if not config.registries:
+                output_console.print("No registries configured.")
+                return
+            clear_cache()
+            for reg_name, entry in config.registries.items():
+                load_index(entry)
+                output_console.print(f"Registry '{reg_name}' updated.")
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
+
+
+@registry_app.command()
+def show(
+    ref: Annotated[
+        str,
+        typer.Argument(help="Workflow reference (name[@registry][@version])."),
+    ],
+) -> None:
+    """Show metadata and cached path for a workflow reference."""
+    try:
+        resolved = resolve_ref(ref)
+        if resolved.kind == "file":
+            output_console.print(f"Local file: {resolved.path}")
+            return
+
+        assert resolved.registry_entry is not None
+        assert resolved.registry_name is not None
+        assert resolved.workflow is not None
+
+        index = load_index(resolved.registry_entry)
+        if resolved.workflow not in index.workflows:
+            raise RegistryError(
+                f"Workflow '{resolved.workflow}' not found in registry '{resolved.registry_name}'",
+            )
+
+        info = index.workflows[resolved.workflow]
+        version = resolved.version or (info.versions[-1] if info.versions else None)
+
+        output_console.print(f"[bold]Workflow:[/bold]  {resolved.workflow}")
+        output_console.print(f"[bold]Registry:[/bold]  {resolved.registry_name}")
+        output_console.print(f"[bold]Description:[/bold] {info.description or '-'}")
+        output_console.print(f"[bold]Path:[/bold]      {info.path}")
+        output_console.print(
+            f"[bold]Versions:[/bold]  {', '.join(info.versions) if info.versions else '-'}"
+        )
+        output_console.print(f"[bold]Version:[/bold]   {version or 'latest'}")
+
+        if version:
+            cached = get_cached_workflow_path(resolved.registry_name, resolved.workflow, version)
+            output_console.print(f"[bold]Cached:[/bold]    {cached or 'not cached'}")
+    except RegistryError as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(code=1) from None
diff --git a/src/conductor/registry/__init__.py b/src/conductor/registry/__init__.py
new file mode 100644
index 0000000..6ea094f
--- /dev/null
+++ b/src/conductor/registry/__init__.py
@@ -0,0 +1,3 @@
+"""Workflow registry system for discovering and managing shared workflows."""
+
+from __future__ import annotations
diff --git a/src/conductor/registry/cache.py b/src/conductor/registry/cache.py
new file mode 100644
index 0000000..a4bbf2b
--- /dev/null
+++ b/src/conductor/registry/cache.py
@@ -0,0 +1,270 @@
+"""Local workflow cache management.
+
+Manages the on-disk cache at ``~/.conductor/cache/registries/`` (or under
+``$CONDUCTOR_HOME``).  Workflows fetched from remote registries are stored
+here so that subsequent runs can resolve to a stable filesystem path — a
+requirement for ``!file`` tag resolution and checkpoint identity.
+
+Cache layout::
+
+    <base>/cache/registries/<registry>/<workflow>/<version>/
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from conductor.registry.config import RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+from conductor.registry.github import fetch_file, list_directory, parse_github_source
+from conductor.registry.index import load_index, resolve_latest
+
+# fetch_file returns bytes; list_directory returns filenames (not full paths)
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def get_cache_base() -> Path:
+    """Return the base cache directory.
+
+    Uses ``$CONDUCTOR_HOME/cache/registries/`` or
+    ``~/.conductor/cache/registries/``.
+    """
+    home = os.environ.get("CONDUCTOR_HOME")
+    base = Path(home) if home else Path.home() / ".conductor"
+    return base / "cache" / "registries"
+
+
+def get_cached_workflow_path(
+    registry_name: str,
+    workflow_name: str,
+    version: str,
+) -> Path | None:
+    """Return the cached workflow YAML path if it exists, else ``None``.
+
+    Looks for the workflow at::
+
+        <cache_base>/<registry_name>/<workflow_name>/<version>/
+
+    The filename is derived from a glob of ``*.yaml`` / ``*.yml`` files in the
+    version directory.  Returns the first YAML file found (there should be
+    exactly one workflow file per cached version directory).
+
+    Args:
+        registry_name: Name of the registry.
+        workflow_name: Name of the workflow.
+        version: Resolved version string.
+
+    Returns:
+        ``Path`` to the cached workflow YAML, or ``None`` when not cached.
+    """
+    version_dir = get_cache_base() / registry_name / workflow_name / version
+    if not version_dir.is_dir():
+        return None
+
+    for ext in ("*.yaml", "*.yml"):
+        matches = list(version_dir.glob(ext))
+        if matches:
+            return matches[0]
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Fetch + cache
+# ---------------------------------------------------------------------------
+
+
+def fetch_workflow(
+    registry_name: str,
+    registry_entry: RegistryEntry,
+    workflow_name: str,
+    version: str | None = None,
+) -> Path:
+    """Fetch a workflow from a registry and cache it locally.
+
+    Steps:
+
+    1. Load the registry index.
+    2. Resolve version (if ``None``, resolve ``latest``).
+    3. Check cache — return cached path if explicit version already present.
+    4. Fetch the workflow file **and** sibling files in the same directory.
+    5. Write everything to the cache directory.
+    6. Return the ``Path`` to the cached workflow YAML.
+
+    For **GitHub** registries files are fetched at the git tag matching the
+    version via :func:`~conductor.registry.github.fetch_file` and siblings
+    are enumerated with :func:`~conductor.registry.github.list_directory`.
+
+    For **path** registries files are copied from the source directory to
+    guarantee a stable snapshot even when the source changes.
+
+    Args:
+        registry_name: Configured registry name.
+        registry_entry: The registry definition (type + source).
+        workflow_name: Workflow key as listed in the registry index.
+        version: Explicit version string, or ``None`` for ``latest``.
+
+    Returns:
+        Path to the cached workflow YAML file.
+
+    Raises:
+        RegistryError: On fetch failure, missing workflow, or I/O errors.
+    """
+    # 1. Load the index
+    index = load_index(registry_entry)
+
+    # 2. Resolve version
+    if version is None:
+        version = resolve_latest(index, workflow_name)
+
+    # 3. Look up workflow metadata from the index
+    if workflow_name not in index.workflows:
+        raise RegistryError(
+            f"Workflow '{workflow_name}' not found in registry '{registry_name}'",
+            suggestion=f"Run 'conductor registry list {registry_name}' to see available workflows.",
+        )
+    workflow_info = index.workflows[workflow_name]
+
+    # 4. Check cache (explicit versions are immutable)
+    cached = get_cached_workflow_path(registry_name, workflow_name, version)
+    if cached is not None:
+        return cached
+
+    # 5. Prepare cache directory
+    version_dir = get_cache_base() / registry_name / workflow_name / version
+    version_dir.mkdir(parents=True, exist_ok=True)
+
+    # 6. Fetch based on registry type
+    try:
+        if registry_entry.type == RegistryType.github:
+            _fetch_github(registry_entry, workflow_info.path, version, version_dir)
+        else:
+            _fetch_path(registry_entry, workflow_info.path, version_dir)
+    except RegistryError:
+        raise
+    except Exception as exc:
+        raise RegistryError(
+            f"Failed to fetch workflow '{workflow_name}' from registry '{registry_name}': {exc}",
+            suggestion="Check your network connection and registry configuration.",
+        ) from exc
+
+    # 7. Return the cached workflow path
+    workflow_filename = Path(workflow_info.path).name
+    result = version_dir / workflow_filename
+    if not result.exists():
+        raise RegistryError(
+            f"Workflow file '{workflow_filename}' not found in cache after fetch",
+            suggestion="The registry index may reference a file that does not exist.",
+        )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# GitHub fetch
+# ---------------------------------------------------------------------------
+
+
+def _fetch_github(
+    registry_entry: RegistryEntry,
+    workflow_path: str,
+    version: str,
+    dest_dir: Path,
+) -> None:
+    """Fetch a workflow and its sibling files from a GitHub registry.
+
+    Args:
+        registry_entry: Registry entry with ``source`` as ``owner/repo``.
+        workflow_path: Relative path to the workflow YAML in the repo.
+        version: Git ref (tag) to fetch at.
+        dest_dir: Local directory to write files into.
+    """
+    owner, repo = parse_github_source(registry_entry.source)
+    workflow_p = Path(workflow_path)
+    parent_dir = str(workflow_p.parent)
+    workflow_filename = workflow_p.name
+
+    # Fetch the workflow file itself (returns bytes)
+    content = fetch_file(owner, repo, workflow_path, ref=version)
+    (dest_dir / workflow_filename).write_bytes(content)
+
+    # Fetch sibling files — list_directory returns filenames (not full paths)
+    try:
+        sibling_names = list_directory(owner, repo, parent_dir, ref=version)
+    except Exception:
+        # If listing fails, we already have the workflow file
+        return
+
+    for name in sibling_names:
+        if name == workflow_filename:
+            continue  # already fetched
+        sibling_repo_path = f"{parent_dir}/{name}" if parent_dir != "." else name
+        try:
+            sibling_content = fetch_file(owner, repo, sibling_repo_path, ref=version)
+            (dest_dir / name).write_bytes(sibling_content)
+        except Exception:
+            # Best-effort for siblings — don't fail the whole fetch
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Path (local) fetch
+# ---------------------------------------------------------------------------
+
+
+def _fetch_path(
+    registry_entry: RegistryEntry,
+    workflow_path: str,
+    dest_dir: Path,
+) -> None:
+    """Copy a workflow and its sibling files from a local path registry.
+
+    Args:
+        registry_entry: Registry entry with ``source`` as a filesystem path.
+        workflow_path: Relative path to the workflow YAML within the source.
+        dest_dir: Local directory to write files into.
+    """
+    source_root = Path(registry_entry.source)
+    source_file = source_root / workflow_path
+
+    if not source_file.exists():
+        raise RegistryError(
+            f"Workflow file not found at '{source_file}'",
+            suggestion="Verify the 'path' field in the registry's index.yaml.",
+            file_path=str(source_file),
+        )
+
+    source_dir = source_file.parent
+
+    # Copy all files in the workflow's directory
+    for item in source_dir.iterdir():
+        if item.is_file():
+            shutil.copy2(item, dest_dir / item.name)
+
+
+# ---------------------------------------------------------------------------
+# Cache management
+# ---------------------------------------------------------------------------
+
+
+def clear_cache(registry_name: str | None = None) -> None:
+    """Clear cached workflows.
+
+    If *registry_name* is provided only that registry's cache is removed.
+    Otherwise **all** cached registries are deleted.
+
+    Args:
+        registry_name: Optional registry name to scope the clear.
+    """
+    base = get_cache_base()
+
+    if registry_name is not None:
+        target = base / registry_name
+        if target.exists():
+            shutil.rmtree(target)
+    else:
+        if base.exists():
+            shutil.rmtree(base)
diff --git a/src/conductor/registry/config.py b/src/conductor/registry/config.py
new file mode 100644
index 0000000..39d52fa
--- /dev/null
+++ b/src/conductor/registry/config.py
@@ -0,0 +1,256 @@
+"""Registry configuration management.
+
+Handles loading, saving, and modifying the registries config file
+stored at ``~/.conductor/registries.toml`` (or under ``$CONDUCTOR_HOME``).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, model_validator
+
+from conductor.registry.errors import RegistryError
+
+_GITHUB_SOURCE_RE = re.compile(r"^[a-zA-Z0-9_.\-]+/[a-zA-Z0-9_.\-]+$")
+
+CONFIG_FILENAME = "registries.toml"
+
+
+class RegistryType(StrEnum):
+    """Supported registry backend types."""
+
+    github = "github"
+    path = "path"
+
+
+class RegistryEntry(BaseModel):
+    """A single registry definition."""
+
+    type: RegistryType
+    """Backend type — ``github`` or ``path``."""
+
+    source: str
+    """Location of workflows. ``owner/repo`` for github, filesystem path for path."""
+
+
+class RegistriesConfig(BaseModel):
+    """Top-level registries configuration."""
+
+    default: str | None = None
+    """Name of the default registry, must be a key in ``registries``."""
+
+    registries: dict[str, RegistryEntry] = {}
+    """Mapping of registry name to its entry."""
+
+    @model_validator(mode="after")
+    def _validate_default(self) -> RegistriesConfig:
+        """Ensure ``default`` references an existing registry."""
+        if self.default is not None and self.default not in self.registries:
+            raise ValueError(f"default registry '{self.default}' is not defined in registries")
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def get_config_path() -> Path:
+    """Return the path to the registries config file.
+
+    Respects the ``CONDUCTOR_HOME`` environment variable. Falls back to
+    ``~/.conductor``.
+    """
+    home = os.environ.get("CONDUCTOR_HOME")
+    base = Path(home) if home else Path.home() / ".conductor"
+    return base / CONFIG_FILENAME
+
+
+# ---------------------------------------------------------------------------
+# Load / save
+# ---------------------------------------------------------------------------
+
+
+def load_config() -> RegistriesConfig:
+    """Load the registries configuration from disk.
+
+    Returns:
+        Parsed ``RegistriesConfig``. An empty config is returned when the
+        file does not exist.
+
+    Raises:
+        RegistryError: If the file exists but contains malformed TOML or
+            invalid data.
+    """
+    path = get_config_path()
+    if not path.exists():
+        return RegistriesConfig()
+
+    try:
+        with open(path, "rb") as f:
+            raw = tomllib.load(f)
+    except tomllib.TOMLDecodeError as exc:
+        raise RegistryError(
+            f"Failed to parse {path}: {exc}",
+            suggestion="Check the TOML syntax in your registries config file.",
+            file_path=str(path),
+        ) from exc
+
+    try:
+        return RegistriesConfig.model_validate(raw)
+    except Exception as exc:
+        raise RegistryError(
+            f"Invalid registry config in {path}: {exc}",
+            suggestion="Verify the structure of your registries config file.",
+            file_path=str(path),
+        ) from exc
+
+
+def save_config(config: RegistriesConfig) -> None:
+    """Atomically write the registries config to disk.
+
+    Creates parent directories as needed. Writes to a temporary file in the
+    same directory then renames to ensure atomicity.
+
+    Args:
+        config: The configuration to persist.
+    """
+    path = get_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = _format_toml(config)
+
+    tmp_path = path.with_suffix(".toml.tmp")
+    try:
+        tmp_path.write_text(content, encoding="utf-8")
+        tmp_path.replace(path)
+    except Exception:
+        # Clean up the temp file on failure
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+
+def _format_toml(config: RegistriesConfig) -> str:
+    """Format a ``RegistriesConfig`` as TOML text."""
+    lines: list[str] = []
+
+    if config.default is not None:
+        lines.append(f'default = "{config.default}"')
+
+    for name, entry in config.registries.items():
+        lines.append("")
+        lines.append(f"[registries.{name}]")
+        lines.append(f'type = "{entry.type}"')
+        lines.append(f'source = "{entry.source}"')
+
+    # Ensure trailing newline
+    lines.append("")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# High-level helpers
+# ---------------------------------------------------------------------------
+
+
+def _infer_type(source: str) -> RegistryType:
+    """Infer registry type from the source string."""
+    if _GITHUB_SOURCE_RE.match(source):
+        return RegistryType.github
+    return RegistryType.path
+
+
+def add_registry(
+    name: str,
+    source: str,
+    registry_type: RegistryType | None = None,
+    set_default: bool = False,
+) -> RegistriesConfig:
+    """Add a new registry entry and persist the config.
+
+    Args:
+        name: Unique name for the registry.
+        source: Location — ``owner/repo`` for github, filesystem path for path.
+        registry_type: Explicit type; auto-inferred from *source* when ``None``.
+        set_default: If ``True``, make this the default registry.
+
+    Returns:
+        The updated ``RegistriesConfig``.
+
+    Raises:
+        RegistryError: If a registry with *name* already exists.
+    """
+    config = load_config()
+
+    if name in config.registries:
+        raise RegistryError(
+            f"Registry '{name}' already exists",
+            suggestion=f"Use a different name or remove '{name}' first.",
+        )
+
+    resolved_type = registry_type if registry_type is not None else _infer_type(source)
+
+    config.registries[name] = RegistryEntry(type=resolved_type, source=source)
+    if set_default:
+        config.default = name
+
+    save_config(config)
+    return config
+
+
+def remove_registry(name: str) -> RegistriesConfig:
+    """Remove a registry entry and persist the config.
+
+    If the removed registry was the default, the default is cleared.
+
+    Args:
+        name: Name of the registry to remove.
+
+    Returns:
+        The updated ``RegistriesConfig``.
+
+    Raises:
+        RegistryError: If no registry with *name* exists.
+    """
+    config = load_config()
+
+    if name not in config.registries:
+        raise RegistryError(
+            f"Registry '{name}' not found",
+            suggestion="Run 'conductor registry list' to see available registries.",
+        )
+
+    del config.registries[name]
+    if config.default == name:
+        config.default = None
+
+    save_config(config)
+    return config
+
+
+def get_registry(name: str) -> RegistryEntry:
+    """Look up a single registry by name.
+
+    Args:
+        name: Name of the registry.
+
+    Returns:
+        The matching ``RegistryEntry``.
+
+    Raises:
+        RegistryError: If no registry with *name* exists.
+    """
+    config = load_config()
+
+    if name not in config.registries:
+        raise RegistryError(
+            f"Registry '{name}' not found",
+            suggestion="Run 'conductor registry list' to see available registries.",
+        )
+
+    return config.registries[name]
diff --git a/src/conductor/registry/errors.py b/src/conductor/registry/errors.py
new file mode 100644
index 0000000..ed3919b
--- /dev/null
+++ b/src/conductor/registry/errors.py
@@ -0,0 +1,13 @@
+"""Registry-specific exceptions."""
+
+from __future__ import annotations
+
+from conductor.exceptions import ConductorError
+
+
+class RegistryError(ConductorError):
+    """Error related to workflow registry operations.
+
+    Raised for registry not found, config parse errors,
+    and duplicate registry names.
+    """
diff --git a/src/conductor/registry/github.py b/src/conductor/registry/github.py
new file mode 100644
index 0000000..a0dfde5
--- /dev/null
+++ b/src/conductor/registry/github.py
@@ -0,0 +1,176 @@
+"""Helpers for fetching files, tags, and directory contents from public GitHub repos."""
+
+from __future__ import annotations
+
+import httpx
+
+from conductor.registry.errors import RegistryError
+
+GITHUB_RAW_BASE = "https://raw.githubusercontent.com"
+GITHUB_API_BASE = "https://api.github.com"
+DEFAULT_TIMEOUT = 30.0
+
+_HEADERS = {"User-Agent": "conductor-cli"}
+_API_HEADERS = {
+    **_HEADERS,
+    "Accept": "application/vnd.github.v3+json",
+}
+
+
+def _raise_for_status(response: httpx.Response, *, context: str) -> None:
+    """Check response status and raise RegistryError with helpful messages."""
+    if response.is_success:
+        return
+    status = response.status_code
+    if status == 404:
+        raise RegistryError(
+            f"{context}: not found (404). Check that the repository is public and the ref exists."
+        )
+    if status in (403, 429):
+        raise RegistryError(
+            f"{context}: HTTP {status}. GitHub API rate limit may be exceeded. Try again later."
+        )
+    raise RegistryError(f"{context}: HTTP {status}")
+
+
+def fetch_file(owner: str, repo: str, path: str, ref: str = "main") -> bytes:
+    """Fetch a single file from a GitHub repo at a given ref.
+
+    Uses raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        path: File path within the repo.
+        ref: Git ref — branch, tag, or commit SHA. Defaults to "main".
+
+    Returns:
+        Raw file content as bytes.
+
+    Raises:
+        RegistryError: If the file is not found (404) or request fails.
+    """
+    url = f"{GITHUB_RAW_BASE}/{owner}/{repo}/{ref}/{path}"
+    try:
+        response = httpx.get(url, headers=_HEADERS, timeout=DEFAULT_TIMEOUT, follow_redirects=True)
+    except httpx.TimeoutException as exc:
+        raise RegistryError(f"Timeout fetching {owner}/{repo}/{path} at ref {ref}") from exc
+    except httpx.HTTPError as exc:
+        raise RegistryError(f"HTTP error fetching {owner}/{repo}/{path}: {exc}") from exc
+
+    _raise_for_status(response, context=f"Fetching {owner}/{repo}/{path} at ref {ref}")
+    return response.content
+
+
+def fetch_file_text(owner: str, repo: str, path: str, ref: str = "main") -> str:
+    """Like fetch_file but returns decoded text (UTF-8).
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        path: File path within the repo.
+        ref: Git ref — branch, tag, or commit SHA. Defaults to "main".
+
+    Returns:
+        File content decoded as UTF-8 text.
+
+    Raises:
+        RegistryError: If the file is not found (404) or request fails.
+    """
+    return fetch_file(owner, repo, path, ref).decode("utf-8")
+
+
+def list_tags(owner: str, repo: str) -> list[str]:
+    """List all git tags for a repository, newest first.
+
+    Uses GET /repos/{owner}/{repo}/tags from the GitHub REST API.
+    Returns just the tag names as strings.
+    No pagination in v1 — returns first page (up to 100).
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+
+    Returns:
+        List of tag name strings, newest first.
+
+    Raises:
+        RegistryError: If the API request fails.
+    """
+    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/tags"
+    try:
+        response = httpx.get(
+            url, headers=_API_HEADERS, timeout=DEFAULT_TIMEOUT, follow_redirects=True
+        )
+    except httpx.TimeoutException as exc:
+        raise RegistryError(f"Timeout listing tags for {owner}/{repo}") from exc
+    except httpx.HTTPError as exc:
+        raise RegistryError(f"HTTP error listing tags for {owner}/{repo}: {exc}") from exc
+
+    _raise_for_status(response, context=f"Listing tags for {owner}/{repo}")
+    return [tag["name"] for tag in response.json()]
+
+
+def list_directory(owner: str, repo: str, path: str, ref: str = "main") -> list[str]:
+    """List files in a directory of a GitHub repo.
+
+    Uses the Contents API:
+    GET /repos/{owner}/{repo}/contents/{path}?ref={ref}
+
+    Returns names of files only (not subdirectories).
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        path: Directory path within the repo.
+        ref: Git ref. Defaults to "main".
+
+    Returns:
+        List of filenames in the directory (files only, not subdirs).
+
+    Raises:
+        RegistryError: If the directory is not found or request fails.
+    """
+    url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/contents/{path}"
+    params = {"ref": ref}
+    try:
+        response = httpx.get(
+            url,
+            params=params,
+            headers=_API_HEADERS,
+            timeout=DEFAULT_TIMEOUT,
+            follow_redirects=True,
+        )
+    except httpx.TimeoutException as exc:
+        raise RegistryError(
+            f"Timeout listing directory {owner}/{repo}/{path} at ref {ref}"
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise RegistryError(f"HTTP error listing directory {owner}/{repo}/{path}: {exc}") from exc
+
+    _raise_for_status(response, context=f"Listing directory {owner}/{repo}/{path} at ref {ref}")
+
+    items = response.json()
+    if not isinstance(items, list):
+        raise RegistryError(
+            f"Expected a directory at {owner}/{repo}/{path}, but got a single file."
+        )
+    return [item["name"] for item in items if item.get("type") == "file"]
+
+
+def parse_github_source(source: str) -> tuple[str, str]:
+    """Parse 'owner/repo' source string into (owner, repo) tuple.
+
+    Args:
+        source: A string in the format "owner/repo".
+
+    Returns:
+        Tuple of (owner, repo).
+
+    Raises:
+        RegistryError: If the source doesn't match expected format.
+    """
+    parts = source.split("/")
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise RegistryError(f"Invalid GitHub source '{source}'. Expected format: 'owner/repo'.")
+    return parts[0], parts[1]
diff --git a/src/conductor/registry/index.py b/src/conductor/registry/index.py
new file mode 100644
index 0000000..f9b3a22
--- /dev/null
+++ b/src/conductor/registry/index.py
@@ -0,0 +1,248 @@
+"""Registry index loading and parsing.
+
+Handles fetching and parsing ``index.yaml`` / ``index.json`` from local
+path registries and remote GitHub registries.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import httpx
+from pydantic import BaseModel
+from ruamel.yaml import YAML, YAMLError
+
+from conductor.registry.config import RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+
+_GITHUB_RAW_BASE = "https://raw.githubusercontent.com"
+_GITHUB_BRANCHES = ("main", "master")
+_INDEX_FILENAMES = ("index.yaml", "index.json")
+
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+
+class WorkflowInfo(BaseModel):
+    """Metadata about a workflow in a registry index."""
+
+    description: str = ""
+    path: str
+    """Relative path from registry root to the workflow YAML."""
+    versions: list[str] = []
+
+
+class RegistryIndex(BaseModel):
+    """Parsed registry index."""
+
+    workflows: dict[str, WorkflowInfo] = {}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def load_index(entry: RegistryEntry) -> RegistryIndex:
+    """Load and parse the index for a registry.
+
+    For path registries: reads ``index.yaml`` or ``index.json`` from the
+    source directory.
+
+    For GitHub registries: fetches from ``raw.githubusercontent.com`` on the
+    default branch (``main``, falling back to ``master``).
+
+    Args:
+        entry: The registry entry describing the backend type and source.
+
+    Returns:
+        A parsed ``RegistryIndex``.
+
+    Raises:
+        RegistryError: If the index is not found or malformed.
+    """
+    if entry.type == RegistryType.path:
+        return _load_path_index(entry.source)
+    return _load_github_index(entry.source)
+
+
+def resolve_latest(index: RegistryIndex, workflow_name: str) -> str:
+    """Resolve 'latest' to the last version in the versions list.
+
+    Args:
+        index: The registry index to look up.
+        workflow_name: Name of the workflow.
+
+    Returns:
+        The last element of the workflow's versions list.
+
+    Raises:
+        RegistryError: If the workflow is not found or has no versions listed.
+    """
+    info = get_workflow_info(index, workflow_name)
+    if not info.versions:
+        raise RegistryError(
+            f"Workflow '{workflow_name}' has no versions listed",
+            suggestion="Add at least one version to the workflow entry in the registry index.",
+        )
+    return info.versions[-1]
+
+
+def get_workflow_info(index: RegistryIndex, workflow_name: str) -> WorkflowInfo:
+    """Get info for a specific workflow.
+
+    Args:
+        index: The registry index to look up.
+        workflow_name: Name of the workflow.
+
+    Returns:
+        The ``WorkflowInfo`` for the workflow.
+
+    Raises:
+        RegistryError: If the workflow is not found.
+    """
+    if workflow_name not in index.workflows:
+        available = ", ".join(sorted(index.workflows)) or "(none)"
+        raise RegistryError(
+            f"Workflow '{workflow_name}' not found in registry index",
+            suggestion=f"Available workflows: {available}",
+        )
+    return index.workflows[workflow_name]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_index_data(raw: dict, source_label: str) -> RegistryIndex:
+    """Validate and parse raw dict data into a ``RegistryIndex``."""
+    try:
+        return RegistryIndex.model_validate(raw)
+    except Exception as exc:
+        raise RegistryError(
+            f"Malformed registry index from {source_label}: {exc}",
+            suggestion="Check that the index file matches the expected schema.",
+        ) from exc
+
+
+def _load_path_index(source: str) -> RegistryIndex:
+    """Load index from a local filesystem path."""
+    root = Path(source)
+    if not root.is_dir():
+        raise RegistryError(
+            f"Registry path does not exist: {source}",
+            suggestion="Check that the path is correct and the directory exists.",
+        )
+
+    # Try index.yaml first, then index.json
+    yaml_path = root / "index.yaml"
+    json_path = root / "index.json"
+
+    if yaml_path.is_file():
+        return _parse_yaml_file(yaml_path)
+    if json_path.is_file():
+        return _parse_json_file(json_path)
+
+    raise RegistryError(
+        f"No index.yaml or index.json found in {source}",
+        suggestion="Create an index.yaml or index.json in the registry root.",
+    )
+
+
+def _parse_yaml_file(path: Path) -> RegistryIndex:
+    """Parse a YAML index file."""
+    try:
+        yaml = YAML(typ="safe")
+        with open(path) as f:
+            data = yaml.load(f)
+    except YAMLError as exc:
+        raise RegistryError(
+            f"Failed to parse {path}: {exc}",
+            suggestion="Check the YAML syntax in the index file.",
+            file_path=str(path),
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise RegistryError(
+            f"Malformed registry index from {path}: expected a mapping at the top level",
+            suggestion="Check that the index file matches the expected schema.",
+            file_path=str(path),
+        )
+    return _parse_index_data(data, str(path))
+
+
+def _parse_json_file(path: Path) -> RegistryIndex:
+    """Parse a JSON index file."""
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except json.JSONDecodeError as exc:
+        raise RegistryError(
+            f"Failed to parse {path}: {exc}",
+            suggestion="Check the JSON syntax in the index file.",
+            file_path=str(path),
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise RegistryError(
+            f"Malformed registry index from {path}: expected a mapping at the top level",
+            suggestion="Check that the index file matches the expected schema.",
+            file_path=str(path),
+        )
+    return _parse_index_data(data, str(path))
+
+
+def _load_github_index(source: str) -> RegistryIndex:
+    """Fetch index from a GitHub repository via raw.githubusercontent.com."""
+    # source is "owner/repo"
+    for filename in _INDEX_FILENAMES:
+        for branch in _GITHUB_BRANCHES:
+            url = f"{_GITHUB_RAW_BASE}/{source}/{branch}/{filename}"
+            try:
+                resp = httpx.get(url, timeout=30, follow_redirects=True)
+            except httpx.HTTPError as exc:
+                raise RegistryError(
+                    f"Failed to fetch registry index from {url}: {exc}",
+                    suggestion="Check your network connection and the registry source.",
+                ) from exc
+
+            if resp.status_code == 200:
+                return _parse_github_response(resp.text, filename, url)
+
+    raise RegistryError(
+        f"No index.yaml or index.json found in GitHub repo '{source}' "
+        f"(tried branches: {', '.join(_GITHUB_BRANCHES)})",
+        suggestion="Ensure the repository contains an index.yaml or index.json on main or master.",
+    )
+
+
+def _parse_github_response(text: str, filename: str, url: str) -> RegistryIndex:
+    """Parse the content fetched from GitHub."""
+    if filename.endswith(".yaml"):
+        try:
+            yaml = YAML(typ="safe")
+            data = yaml.load(text)
+        except YAMLError as exc:
+            raise RegistryError(
+                f"Failed to parse index from {url}: {exc}",
+                suggestion="Check the YAML syntax in the remote index file.",
+            ) from exc
+    else:
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise RegistryError(
+                f"Failed to parse index from {url}: {exc}",
+                suggestion="Check the JSON syntax in the remote index file.",
+            ) from exc
+
+    if not isinstance(data, dict):
+        raise RegistryError(
+            f"Malformed registry index from {url}: expected a mapping at the top level",
+            suggestion="Check that the index file matches the expected schema.",
+        )
+    return _parse_index_data(data, url)
diff --git a/src/conductor/registry/resolver.py b/src/conductor/registry/resolver.py
new file mode 100644
index 0000000..52f4d0c
--- /dev/null
+++ b/src/conductor/registry/resolver.py
@@ -0,0 +1,129 @@
+"""Workflow reference resolution.
+
+Parses user-supplied workflow references (e.g. ``qa-bot@team@1.2.3``) and
+determines whether an argument is a local file path or a registry reference.
+
+Resolution rules (in order):
+1. If the argument exists as a file on disk, treat it as a local path.
+2. If it looks like a file path (has path separators or YAML extension), treat
+   it as a local path — even if the file doesn't exist yet.
+3. Otherwise parse as a registry reference using ``name[@registry][@version]``
+   syntax.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from conductor.registry.config import RegistryEntry, load_config
+from conductor.registry.errors import RegistryError
+
+_YAML_EXTENSIONS = {".yaml", ".yml"}
+
+
+@dataclass(frozen=True)
+class ResolvedRef:
+    """A resolved workflow reference."""
+
+    kind: Literal["file", "registry"]
+
+    # For file refs
+    path: Path | None = None
+
+    # For registry refs
+    workflow: str | None = None
+    registry_name: str | None = None
+    version: str | None = None  # None means "latest"
+    registry_entry: RegistryEntry | None = None
+
+
+def resolve_ref(ref: str) -> ResolvedRef:
+    """Resolve a workflow reference string to a :class:`ResolvedRef`.
+
+    If *ref* is an existing file path or looks like a file path (contains path
+    separators or has a ``.yaml``/``.yml`` extension), a **file** ref is
+    returned.  Otherwise *ref* is parsed as a registry reference using
+    ``name[@registry][@version]`` syntax.
+
+    Args:
+        ref: The raw reference string from the CLI.
+
+    Returns:
+        A :class:`ResolvedRef` describing the resolved target.
+
+    Raises:
+        RegistryError: If the reference requires a default registry but none is
+            configured, or if the named registry does not exist.
+    """
+    if _looks_like_file_path(ref):
+        return ResolvedRef(kind="file", path=Path(ref))
+
+    return _parse_registry_ref(ref)
+
+
+def _looks_like_file_path(ref: str) -> bool:
+    """Heuristic: is *ref* a file path rather than a registry reference?
+
+    Returns ``True`` when any of the following hold:
+
+    * The ref exists as a file on disk.
+    * The ref contains a path separator (``/`` or ``\\``).
+    * The ref ends with ``.yaml`` or ``.yml``.
+    """
+    if "/" in ref or "\\" in ref:
+        return True
+
+    if Path(ref).suffix.lower() in _YAML_EXTENSIONS:
+        return True
+
+    path = Path(ref)
+    return path.exists() and path.is_file()
+
+
+def _parse_registry_ref(ref: str) -> ResolvedRef:
+    """Parse *ref* as ``name[@registry][@version]`` and resolve against config.
+
+    Raises:
+        RegistryError: On missing default registry or unknown registry name.
+    """
+    parts = ref.split("@", maxsplit=2)
+
+    workflow = parts[0]
+    raw_registry: str | None = parts[1] if len(parts) >= 2 else None
+    version: str | None = parts[2] if len(parts) >= 3 else None
+
+    config = load_config()
+
+    # Determine the registry name: empty string or None → use default.
+    if raw_registry is None or raw_registry == "":
+        if config.default is None:
+            raise RegistryError(
+                "No default registry configured",
+                suggestion=(
+                    "Run 'conductor registry add <name> <source> --default' to "
+                    "configure a default registry."
+                ),
+            )
+        registry_name = config.default
+    else:
+        registry_name = raw_registry
+
+    if registry_name not in config.registries:
+        available = ", ".join(sorted(config.registries)) or "(none)"
+        raise RegistryError(
+            f"Registry '{registry_name}' not found",
+            suggestion=(
+                f"Available registries: {available}. "
+                "Run 'conductor registry list' to see all registries."
+            ),
+        )
+
+    return ResolvedRef(
+        kind="registry",
+        workflow=workflow,
+        registry_name=registry_name,
+        version=version,
+        registry_entry=config.registries[registry_name],
+    )
diff --git a/src/conductor/templates/human-gate.yaml b/src/conductor/templates/human-gate.yaml
deleted file mode 100644
index 1c17836..0000000
--- a/src/conductor/templates/human-gate.yaml
+++ /dev/null
@@ -1,49 +0,0 @@
-# Human gate workflow template
-# A workflow with human-in-the-loop approval
-
-workflow:
-  name: {{ name }}
-  description: A workflow with human gate for approval decisions
-  entry_point: content_creator
-
-agents:
-  - name: content_creator
-    model: gpt-5.2
-    prompt: |
-      Create content based on the following request:
-      {{ '{{' }} workflow.input.request {{ '}}' }}
-    output:
-      content:
-        type: string
-        description: The created content
-      summary:
-        type: string
-        description: A brief summary of the content
-    routes:
-      - to: human_review
-
-  - name: human_review
-    type: human_gate
-    prompt: |
-      Please review the following content:
-
-      {{ '{{' }} content_creator.output.summary {{ '}}' }}
-
-      ---
-      Full content:
-      {{ '{{' }} content_creator.output.content {{ '}}' }}
-    options:
-      - label: Approve
-        value: approved
-        route: $end
-      - label: Request Changes
-        value: changes
-        route: content_creator
-        prompt_for: feedback
-      - label: Reject
-        value: rejected
-        route: $end
-
-output:
-  content: "{{ '{{' }} content_creator.output.content {{ '}}' }}"
-  decision: "{{ '{{' }} human_review.output.decision {{ '}}' }}"
diff --git a/src/conductor/templates/loop.yaml b/src/conductor/templates/loop.yaml
deleted file mode 100644
index df32be5..0000000
--- a/src/conductor/templates/loop.yaml
+++ /dev/null
@@ -1,51 +0,0 @@
-# Loop-back workflow template
-# A workflow that can iterate until a condition is met
-
-workflow:
-  name: {{ name }}
-  description: A workflow with loop-back pattern for iterative refinement
-  entry_point: generator
-  limits:
-    max_iterations: 10
-    timeout_seconds: 300
-
-agents:
-  - name: generator
-    model: gpt-5.2
-    prompt: |
-      Generate content based on the following request:
-      {{ '{{' }} workflow.input.request {{ '}}' }}
-
-      {% raw %}{% if reviewer.output %}{% endraw %}
-      Previous feedback: {{ '{{' }} reviewer.output.feedback {{ '}}' }}
-      Please improve based on this feedback.
-      {% raw %}{% endif %}{% endraw %}
-    output:
-      content:
-        type: string
-        description: The generated content
-    routes:
-      - to: reviewer
-
-  - name: reviewer
-    model: gpt-5.2
-    prompt: |
-      Review the following content:
-      {{ '{{' }} generator.output.content {{ '}}' }}
-
-      Provide feedback and indicate if it's approved.
-    output:
-      approved:
-        type: boolean
-        description: Whether the content is approved
-      feedback:
-        type: string
-        description: Feedback for improvement
-    routes:
-      - to: $end
-        when: "{{ '{{' }} output.approved {{ '}}' }}"
-      - to: generator
-
-output:
-  final_content: "{{ '{{' }} generator.output.content {{ '}}' }}"
-  iterations: "{{ '{{' }} context.iteration {{ '}}' }}"
diff --git a/src/conductor/templates/simple.yaml b/src/conductor/templates/simple.yaml
deleted file mode 100644
index 104c235..0000000
--- a/src/conductor/templates/simple.yaml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Simple linear workflow template
-# A minimal workflow with a single agent
-
-workflow:
-  name: {{ name }}
-  description: A simple linear workflow
-  entry_point: main_agent
-
-agents:
-  - name: main_agent
-    model: gpt-5.2
-    prompt: |
-      {{ '{{' }} workflow.input.question {{ '}}' }}
-    output:
-      answer:
-        type: string
-        description: The answer to the question
-    routes:
-      - to: $end
-
-output:
-  result: "{{ '{{' }} main_agent.output.answer {{ '}}' }}"
diff --git a/tests/test_cli/test_init.py b/tests/test_cli/test_init.py
deleted file mode 100644
index de9e298..0000000
--- a/tests/test_cli/test_init.py
+++ /dev/null
@@ -1,255 +0,0 @@
-"""Tests for the init and templates commands.
-
-This module tests:
-- Templates listing
-- Workflow initialization from templates
-- Template rendering
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-from typer.testing import CliRunner
-
-from conductor.cli.app import app
-
-runner = CliRunner()
-
-
-class TestTemplatesCommand:
-    """Tests for the templates command."""
-
-    def test_templates_command_help(self) -> None:
-        """Test that templates --help works."""
-        result = runner.invoke(app, ["templates", "--help"])
-        assert result.exit_code == 0
-        assert "List available workflow templates" in result.output
-
-    def test_templates_lists_available(self) -> None:
-        """Test that templates command lists available templates."""
-        result = runner.invoke(app, ["templates"])
-        assert result.exit_code == 0
-        # Should list the templates we created
-        assert "simple" in result.output
-        assert "loop" in result.output
-        assert "human-gate" in result.output
-
-    def test_templates_shows_descriptions(self) -> None:
-        """Test that templates command shows descriptions."""
-        result = runner.invoke(app, ["templates"])
-        assert result.exit_code == 0
-        # Should include some descriptive text
-        assert "linear" in result.output.lower() or "workflow" in result.output.lower()
-
-
-class TestInitCommand:
-    """Tests for the init command."""
-
-    def test_init_command_help(self) -> None:
-        """Test that init --help works."""
-        result = runner.invoke(app, ["init", "--help"])
-        assert result.exit_code == 0
-        assert "Initialize a new workflow file" in result.output
-
-    def test_init_creates_simple_workflow(self, tmp_path: Path) -> None:
-        """Test initializing with simple template."""
-        # Run in temp directory
-        output_file = tmp_path / "my-workflow.yaml"
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "my-workflow",
-                "--output",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code == 0
-        assert output_file.exists()
-        assert "Created workflow file" in result.output
-
-        # Check content has the workflow name
-        content = output_file.read_text()
-        assert "my-workflow" in content
-
-    def test_init_with_loop_template(self, tmp_path: Path) -> None:
-        """Test initializing with loop template."""
-        output_file = tmp_path / "loop-workflow.yaml"
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "loop-workflow",
-                "--template",
-                "loop",
-                "--output",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code == 0
-        assert output_file.exists()
-
-        content = output_file.read_text()
-        assert "loop-workflow" in content
-        # Loop template should have generator and reviewer
-        assert "generator" in content or "review" in content.lower()
-
-    def test_init_with_human_gate_template(self, tmp_path: Path) -> None:
-        """Test initializing with human-gate template."""
-        output_file = tmp_path / "gate-workflow.yaml"
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "gate-workflow",
-                "--template",
-                "human-gate",
-                "--output",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code == 0
-        assert output_file.exists()
-
-        content = output_file.read_text()
-        assert "gate-workflow" in content
-        # Human gate template should have human_gate type
-        assert "human_gate" in content
-
-    def test_init_invalid_template(self, tmp_path: Path) -> None:
-        """Test init with invalid template name."""
-        output_file = tmp_path / "workflow.yaml"
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "workflow",
-                "--template",
-                "nonexistent",
-                "--output",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code != 0
-        assert "not found" in result.output.lower()
-
-    def test_init_file_already_exists(self, tmp_path: Path) -> None:
-        """Test init when file already exists."""
-        output_file = tmp_path / "existing.yaml"
-        output_file.write_text("existing content")
-
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "existing",
-                "--output",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code != 0
-        assert "exists" in result.output.lower()
-
-        # Original content should be unchanged
-        assert output_file.read_text() == "existing content"
-
-    def test_init_default_output_path(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
-        """Test init creates file with default name in current directory."""
-        # Change to temp directory
-        monkeypatch.chdir(tmp_path)
-
-        result = runner.invoke(app, ["init", "test-workflow"])
-
-        assert result.exit_code == 0
-        # Should create test-workflow.yaml in current directory
-        expected_file = tmp_path / "test-workflow.yaml"
-        assert expected_file.exists()
-
-    def test_init_short_template_option(self, tmp_path: Path) -> None:
-        """Test init with short -t option."""
-        output_file = tmp_path / "short-test.yaml"
-        result = runner.invoke(
-            app,
-            [
-                "init",
-                "short-test",
-                "-t",
-                "loop",
-                "-o",
-                str(output_file),
-            ],
-        )
-
-        assert result.exit_code == 0
-        assert output_file.exists()
-
-
-class TestInitHelperFunctions:
-    """Tests for init helper functions."""
-
-    def test_list_templates_returns_all(self) -> None:
-        """Test that list_templates returns all templates."""
-        from conductor.cli.init import list_templates
-
-        templates = list_templates()
-        template_names = [t.name for t in templates]
-
-        assert "simple" in template_names
-        assert "loop" in template_names
-        assert "human-gate" in template_names
-
-    def test_get_template_existing(self) -> None:
-        """Test get_template with existing template."""
-        from conductor.cli.init import get_template
-
-        template = get_template("simple")
-        assert template is not None
-        assert template.name == "simple"
-        assert template.filename == "simple.yaml"
-
-    def test_get_template_nonexistent(self) -> None:
-        """Test get_template with nonexistent template."""
-        from conductor.cli.init import get_template
-
-        template = get_template("nonexistent")
-        assert template is None
-
-    def test_render_template_substitutes_name(self) -> None:
-        """Test that render_template substitutes the workflow name."""
-        from conductor.cli.init import render_template
-
-        content = render_template("simple", "my-awesome-workflow")
-        assert "my-awesome-workflow" in content
-
-    def test_render_template_invalid_raises(self) -> None:
-        """Test that render_template raises for invalid template."""
-        from conductor.cli.init import render_template
-
-        with pytest.raises(ValueError, match="not found"):
-            render_template("nonexistent", "test")
-
-    def test_get_template_dir_exists(self) -> None:
-        """Test that template directory exists."""
-        from conductor.cli.init import get_template_dir
-
-        template_dir = get_template_dir()
-        assert template_dir.exists()
-        assert template_dir.is_dir()
-
-    def test_template_files_exist(self) -> None:
-        """Test that all template files exist."""
-        from conductor.cli.init import TEMPLATES, get_template_dir
-
-        template_dir = get_template_dir()
-        for template in TEMPLATES.values():
-            template_path = template_dir / template.filename
-            assert template_path.exists(), f"Template file missing: {template_path}"
diff --git a/tests/test_cli/test_registry_commands.py b/tests/test_cli/test_registry_commands.py
new file mode 100644
index 0000000..10c021c
--- /dev/null
+++ b/tests/test_cli/test_registry_commands.py
@@ -0,0 +1,258 @@
+"""Tests for the ``conductor registry`` CLI subcommand group."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from typer.testing import CliRunner
+
+from conductor.cli.app import app
+from conductor.registry.index import RegistryIndex, WorkflowInfo
+
+runner = CliRunner()
+
+
+@pytest.fixture(autouse=True)
+def _isolate_config(monkeypatch: pytest.MonkeyPatch, tmp_path: pytest.TempPathFactory) -> None:  # type: ignore[type-arg]
+    """Point CONDUCTOR_HOME to a temp directory so tests don't touch real config."""
+    monkeypatch.setenv("CONDUCTOR_HOME", str(tmp_path))
+
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+
+
+class TestRegistryHelp:
+    """Verify the registry subcommand group is wired up."""
+
+    def test_registry_help(self) -> None:
+        result = runner.invoke(app, ["registry", "--help"])
+        assert result.exit_code == 0
+        assert "registry" in result.output.lower()
+        # All subcommands should be listed
+        for cmd in ("list", "add", "remove", "set-default", "update", "show"):
+            assert cmd in result.output
+
+
+# ---------------------------------------------------------------------------
+# list (no registries)
+# ---------------------------------------------------------------------------
+
+
+class TestListEmpty:
+    """Listing when no registries are configured."""
+
+    def test_list_no_registries(self) -> None:
+        result = runner.invoke(app, ["registry", "list"])
+        assert result.exit_code == 0
+        assert "No registries configured" in result.output
+
+
+# ---------------------------------------------------------------------------
+# add / list
+# ---------------------------------------------------------------------------
+
+
+class TestAddAndList:
+    """Adding registries and listing them."""
+
+    def test_add_registry(self) -> None:
+        result = runner.invoke(app, ["registry", "add", "team", "acme/workflows"])
+        assert result.exit_code == 0
+        assert "team" in result.output
+        assert "added" in result.output
+
+    def test_add_with_default(self) -> None:
+        result = runner.invoke(app, ["registry", "add", "team", "acme/workflows", "--default"])
+        assert result.exit_code == 0
+        assert "default" in result.output.lower()
+
+    def test_add_duplicate_name(self) -> None:
+        runner.invoke(app, ["registry", "add", "dup", "acme/workflows"])
+        result = runner.invoke(app, ["registry", "add", "dup", "acme/other"])
+        assert result.exit_code == 1
+        assert "already exists" in result.output
+
+    def test_list_after_add(self) -> None:
+        runner.invoke(app, ["registry", "add", "myteam", "acme/workflows", "--default"])
+        result = runner.invoke(app, ["registry", "list"])
+        assert result.exit_code == 0
+        assert "myteam" in result.output
+        assert "acme/workflows" in result.output
+        assert "✓" in result.output  # default marker
+
+
+# ---------------------------------------------------------------------------
+# list <name> (workflows)
+# ---------------------------------------------------------------------------
+
+
+class TestListWorkflows:
+    """Listing workflows in a specific registry (index mocked)."""
+
+    def test_list_workflows(self) -> None:
+        runner.invoke(app, ["registry", "add", "team", "acme/workflows"])
+
+        mock_index = RegistryIndex(
+            workflows={
+                "qa-bot": WorkflowInfo(
+                    description="QA helper", path="qa/bot.yaml", versions=["1.0", "1.1"]
+                ),
+                "summarizer": WorkflowInfo(
+                    description="Summarize docs", path="summarizer.yaml", versions=["2.0"]
+                ),
+            }
+        )
+
+        with patch("conductor.cli.registry.load_index", return_value=mock_index):
+            result = runner.invoke(app, ["registry", "list", "team"])
+
+        assert result.exit_code == 0
+        assert "qa-bot" in result.output
+        assert "summarizer" in result.output
+        assert "1.0" in result.output
+
+    def test_list_workflows_unknown_registry(self) -> None:
+        result = runner.invoke(app, ["registry", "list", "nope"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# remove
+# ---------------------------------------------------------------------------
+
+
+class TestRemove:
+    """Removing registries."""
+
+    def test_remove_existing(self) -> None:
+        runner.invoke(app, ["registry", "add", "removeme", "acme/workflows"])
+        result = runner.invoke(app, ["registry", "remove", "removeme"])
+        assert result.exit_code == 0
+        assert "removed" in result.output
+
+        # Should be gone now
+        result = runner.invoke(app, ["registry", "list"])
+        assert "removeme" not in result.output
+
+    def test_remove_nonexistent(self) -> None:
+        result = runner.invoke(app, ["registry", "remove", "ghost"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# set-default
+# ---------------------------------------------------------------------------
+
+
+class TestSetDefault:
+    """Setting the default registry."""
+
+    def test_set_default(self) -> None:
+        runner.invoke(app, ["registry", "add", "first", "acme/a"])
+        runner.invoke(app, ["registry", "add", "second", "acme/b"])
+        result = runner.invoke(app, ["registry", "set-default", "second"])
+        assert result.exit_code == 0
+        assert "second" in result.output
+
+        # Verify via list
+        result = runner.invoke(app, ["registry", "list"])
+        assert "✓" in result.output
+
+    def test_set_default_nonexistent(self) -> None:
+        result = runner.invoke(app, ["registry", "set-default", "nope"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# show
+# ---------------------------------------------------------------------------
+
+
+class TestShow:
+    """Showing workflow metadata."""
+
+    def test_show_workflow(self) -> None:
+        runner.invoke(app, ["registry", "add", "team", "acme/workflows", "--default"])
+
+        mock_index = RegistryIndex(
+            workflows={
+                "qa-bot": WorkflowInfo(
+                    description="QA helper", path="qa/bot.yaml", versions=["1.0", "1.1"]
+                ),
+            }
+        )
+
+        with patch("conductor.cli.registry.load_index", return_value=mock_index):
+            result = runner.invoke(app, ["registry", "show", "qa-bot"])
+
+        assert result.exit_code == 0
+        assert "qa-bot" in result.output
+        assert "QA helper" in result.output
+        assert "qa/bot.yaml" in result.output
+        assert "1.0" in result.output
+
+    def test_show_unknown_workflow(self) -> None:
+        runner.invoke(app, ["registry", "add", "team", "acme/workflows", "--default"])
+
+        mock_index = RegistryIndex(workflows={})
+
+        with patch("conductor.cli.registry.load_index", return_value=mock_index):
+            result = runner.invoke(app, ["registry", "show", "missing"])
+
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+
+# ---------------------------------------------------------------------------
+# update
+# ---------------------------------------------------------------------------
+
+
+class TestUpdate:
+    """Updating registry indexes."""
+
+    def test_update_single(self) -> None:
+        runner.invoke(app, ["registry", "add", "team", "acme/workflows"])
+
+        mock_index = RegistryIndex(workflows={})
+
+        with (
+            patch("conductor.cli.registry.clear_cache") as mock_clear,
+            patch("conductor.cli.registry.load_index", return_value=mock_index),
+        ):
+            result = runner.invoke(app, ["registry", "update", "team"])
+
+        assert result.exit_code == 0
+        assert "updated" in result.output
+        mock_clear.assert_called_once_with("team")
+
+    def test_update_all(self) -> None:
+        runner.invoke(app, ["registry", "add", "a", "acme/a"])
+        runner.invoke(app, ["registry", "add", "b", "acme/b"])
+
+        mock_index = RegistryIndex(workflows={})
+
+        with (
+            patch("conductor.cli.registry.clear_cache") as mock_clear,
+            patch("conductor.cli.registry.load_index", return_value=mock_index),
+        ):
+            result = runner.invoke(app, ["registry", "update"])
+
+        assert result.exit_code == 0
+        mock_clear.assert_called_once_with()  # no args = clear all
+
+    def test_update_nonexistent(self) -> None:
+        result = runner.invoke(app, ["registry", "update", "nope"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
+
+    def test_update_no_registries(self) -> None:
+        result = runner.invoke(app, ["registry", "update"])
+        assert result.exit_code == 0
+        assert "No registries configured" in result.output
diff --git a/tests/test_registry/__init__.py b/tests/test_registry/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_registry/test_cache.py b/tests/test_registry/test_cache.py
new file mode 100644
index 0000000..62be982
--- /dev/null
+++ b/tests/test_registry/test_cache.py
@@ -0,0 +1,362 @@
+"""Tests for the registry cache layer."""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from conductor.registry.cache import (
+    clear_cache,
+    fetch_workflow,
+    get_cache_base,
+    get_cached_workflow_path,
+)
+from conductor.registry.config import RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _setup_conductor_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point CONDUCTOR_HOME at a temp directory and return its path."""
+    home = tmp_path / "conductor_home"
+    home.mkdir()
+    monkeypatch.setenv("CONDUCTOR_HOME", str(home))
+    return home
+
+
+def _create_path_registry(tmp_path: Path) -> Path:
+    """Create a minimal local path registry with one workflow and a sibling.
+
+    Layout::
+
+        tmp_path/my-registry/
+            index.yaml
+            workflows/
+                qa-bot.yaml
+                prompt.txt
+    """
+    registry_dir = tmp_path / "my-registry"
+    wf_dir = registry_dir / "workflows"
+    wf_dir.mkdir(parents=True)
+
+    (registry_dir / "index.yaml").write_text(
+        textwrap.dedent("""\
+            workflows:
+              qa-bot:
+                description: "Simple Q&A"
+                path: workflows/qa-bot.yaml
+                versions: ["1.0.0", "2.0.0"]
+        """),
+        encoding="utf-8",
+    )
+    (wf_dir / "qa-bot.yaml").write_text("name: qa-bot\nagents: []\n", encoding="utf-8")
+    (wf_dir / "prompt.txt").write_text("You are a helpful assistant.\n", encoding="utf-8")
+    return registry_dir
+
+
+class _FakeWorkflowInfo:
+    """Minimal stand-in for WorkflowInfo returned by the index module."""
+
+    def __init__(self, *, description: str, path: str, versions: list[str]) -> None:
+        self.description = description
+        self.path = path
+        self.versions = versions
+
+
+class _FakeIndex:
+    """Minimal stand-in for RegistryIndex returned by load_index."""
+
+    def __init__(self, workflows: dict[str, _FakeWorkflowInfo]) -> None:
+        self.workflows = workflows
+
+
+# ---------------------------------------------------------------------------
+# get_cache_base
+# ---------------------------------------------------------------------------
+
+
+class TestGetCacheBase:
+    def test_default_path(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("CONDUCTOR_HOME", raising=False)
+        result = get_cache_base()
+        assert result == Path.home() / ".conductor" / "cache" / "registries"
+
+    def test_conductor_home_override(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        home = tmp_path / "custom"
+        monkeypatch.setenv("CONDUCTOR_HOME", str(home))
+        result = get_cache_base()
+        assert result == home / "cache" / "registries"
+
+
+# ---------------------------------------------------------------------------
+# get_cached_workflow_path
+# ---------------------------------------------------------------------------
+
+
+class TestGetCachedWorkflowPath:
+    def test_returns_none_when_not_cached(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        result = get_cached_workflow_path("myregistry", "qa-bot", "1.0.0")
+        assert result is None
+
+    def test_returns_path_when_cached(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        version_dir = home / "cache" / "registries" / "myregistry" / "qa-bot" / "1.0.0"
+        version_dir.mkdir(parents=True)
+        wf_file = version_dir / "qa-bot.yaml"
+        wf_file.write_text("name: qa-bot\n", encoding="utf-8")
+
+        result = get_cached_workflow_path("myregistry", "qa-bot", "1.0.0")
+        assert result is not None
+        assert result == wf_file
+
+    def test_returns_none_for_empty_dir(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        version_dir = home / "cache" / "registries" / "myregistry" / "qa-bot" / "1.0.0"
+        version_dir.mkdir(parents=True)
+        # directory exists but has no YAML files
+        result = get_cached_workflow_path("myregistry", "qa-bot", "1.0.0")
+        assert result is None
+
+
+# ---------------------------------------------------------------------------
+# fetch_workflow — path registry
+# ---------------------------------------------------------------------------
+
+
+class TestFetchWorkflowPath:
+    def _make_index(self) -> _FakeIndex:
+        return _FakeIndex(
+            workflows={
+                "qa-bot": _FakeWorkflowInfo(
+                    description="Simple Q&A",
+                    path="workflows/qa-bot.yaml",
+                    versions=["1.0.0", "2.0.0"],
+                ),
+            }
+        )
+
+    @patch("conductor.registry.cache.load_index")
+    def test_fetches_and_caches(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        registry_dir = _create_path_registry(tmp_path)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+
+        entry = RegistryEntry(type=RegistryType.path, source=str(registry_dir))
+        result = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+
+        assert result.exists()
+        assert result.name == "qa-bot.yaml"
+        assert "local" in str(result)
+        assert "1.0.0" in str(result)
+
+        # Sibling file should be cached too
+        sibling = result.parent / "prompt.txt"
+        assert sibling.exists()
+
+        # Verify cache directory is under CONDUCTOR_HOME
+        assert str(result).startswith(str(home))
+
+    @patch("conductor.registry.cache.load_index")
+    def test_second_fetch_returns_cached(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        registry_dir = _create_path_registry(tmp_path)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+
+        entry = RegistryEntry(type=RegistryType.path, source=str(registry_dir))
+
+        first = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+        second = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+
+        assert first == second
+        # load_index is still called (to check workflow exists + resolve version),
+        # but the file system copy should only happen once
+        assert mock_load_index.call_count == 2  # type: ignore[union-attr]
+
+    @patch("conductor.registry.cache.resolve_latest", return_value="2.0.0")
+    @patch("conductor.registry.cache.load_index")
+    def test_resolves_latest(
+        self,
+        mock_load_index: object,
+        mock_resolve_latest: object,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        registry_dir = _create_path_registry(tmp_path)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+
+        entry = RegistryEntry(type=RegistryType.path, source=str(registry_dir))
+        result = fetch_workflow("local", entry, "qa-bot", version=None)
+
+        mock_resolve_latest.assert_called_once()  # type: ignore[union-attr]
+        assert result.exists()
+        assert "2.0.0" in str(result)
+
+    @patch("conductor.registry.cache.load_index")
+    def test_missing_workflow_raises(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        mock_load_index.return_value = _FakeIndex(workflows={})  # type: ignore[union-attr]
+
+        entry = RegistryEntry(type=RegistryType.path, source=str(tmp_path))
+        with pytest.raises(RegistryError, match="not found"):
+            fetch_workflow("local", entry, "nonexistent", version="1.0.0")
+
+    @patch("conductor.registry.cache.load_index")
+    def test_missing_source_file_raises(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+
+        # Source dir exists but the workflow file doesn't
+        empty_registry = tmp_path / "empty-registry"
+        empty_registry.mkdir()
+        entry = RegistryEntry(type=RegistryType.path, source=str(empty_registry))
+
+        with pytest.raises(RegistryError, match="not found"):
+            fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+
+
+# ---------------------------------------------------------------------------
+# fetch_workflow — GitHub registry
+# ---------------------------------------------------------------------------
+
+
+class TestFetchWorkflowGitHub:
+    def _make_index(self) -> _FakeIndex:
+        return _FakeIndex(
+            workflows={
+                "qa-bot": _FakeWorkflowInfo(
+                    description="Simple Q&A",
+                    path="workflows/qa-bot.yaml",
+                    versions=["1.0.0"],
+                ),
+            }
+        )
+
+    @patch("conductor.registry.cache.fetch_file")
+    @patch("conductor.registry.cache.list_directory")
+    @patch("conductor.registry.cache.parse_github_source", return_value=("myorg", "workflows"))
+    @patch("conductor.registry.cache.load_index")
+    def test_fetches_from_github(
+        self,
+        mock_load_index: object,
+        mock_parse: object,
+        mock_list_dir: object,
+        mock_fetch_file: object,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+        mock_list_dir.return_value = [  # type: ignore[union-attr]
+            "qa-bot.yaml",
+            "prompt.txt",
+        ]
+
+        def fake_fetch(owner: str, repo: str, path: str, *, ref: str) -> bytes:
+            if path.endswith("qa-bot.yaml"):
+                return b"name: qa-bot\nagents: []\n"
+            return b"You are a helpful assistant.\n"
+
+        mock_fetch_file.side_effect = fake_fetch  # type: ignore[union-attr]
+
+        entry = RegistryEntry(type=RegistryType.github, source="myorg/workflows")
+        result = fetch_workflow("official", entry, "qa-bot", version="1.0.0")
+
+        assert result.exists()
+        assert result.name == "qa-bot.yaml"
+        assert "1.0.0" in str(result)
+
+        # Sibling should be cached
+        sibling = result.parent / "prompt.txt"
+        assert sibling.exists()
+
+        mock_parse.assert_called_once_with("myorg/workflows")  # type: ignore[union-attr]
+
+    @patch("conductor.registry.cache.fetch_file")
+    @patch("conductor.registry.cache.list_directory")
+    @patch("conductor.registry.cache.parse_github_source", return_value=("myorg", "workflows"))
+    @patch("conductor.registry.cache.load_index")
+    def test_cached_github_not_refetched(
+        self,
+        mock_load_index: object,
+        mock_parse: object,
+        mock_list_dir: object,
+        mock_fetch_file: object,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
+
+        # Pre-populate the cache
+        version_dir = home / "cache" / "registries" / "official" / "qa-bot" / "1.0.0"
+        version_dir.mkdir(parents=True)
+        (version_dir / "qa-bot.yaml").write_text("name: qa-bot\n", encoding="utf-8")
+
+        entry = RegistryEntry(type=RegistryType.github, source="myorg/workflows")
+        result = fetch_workflow("official", entry, "qa-bot", version="1.0.0")
+
+        assert result.exists()
+        # fetch_file should never have been called — cache hit
+        mock_fetch_file.assert_not_called()  # type: ignore[union-attr]
+        mock_list_dir.assert_not_called()  # type: ignore[union-attr]
+
+
+# ---------------------------------------------------------------------------
+# clear_cache
+# ---------------------------------------------------------------------------
+
+
+class TestClearCache:
+    def test_clear_all(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        cache_base = home / "cache" / "registries"
+
+        # Create two registries in the cache
+        (cache_base / "reg-a" / "wf" / "1.0").mkdir(parents=True)
+        (cache_base / "reg-b" / "wf" / "2.0").mkdir(parents=True)
+
+        clear_cache()
+
+        assert not cache_base.exists()
+
+    def test_clear_specific_registry(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        home = _setup_conductor_home(tmp_path, monkeypatch)
+        cache_base = home / "cache" / "registries"
+
+        (cache_base / "reg-a" / "wf" / "1.0").mkdir(parents=True)
+        (cache_base / "reg-b" / "wf" / "2.0").mkdir(parents=True)
+
+        clear_cache(registry_name="reg-a")
+
+        assert not (cache_base / "reg-a").exists()
+        assert (cache_base / "reg-b").exists()
+
+    def test_clear_nonexistent_is_noop(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_conductor_home(tmp_path, monkeypatch)
+        # Should not raise
+        clear_cache(registry_name="does-not-exist")
+        clear_cache()
diff --git a/tests/test_registry/test_config.py b/tests/test_registry/test_config.py
new file mode 100644
index 0000000..dd4c99a
--- /dev/null
+++ b/tests/test_registry/test_config.py
@@ -0,0 +1,279 @@
+"""Tests for registry configuration module."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from conductor.registry.config import (
+    RegistriesConfig,
+    RegistryEntry,
+    RegistryType,
+    add_registry,
+    get_config_path,
+    get_registry,
+    load_config,
+    remove_registry,
+    save_config,
+)
+from conductor.registry.errors import RegistryError
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _setup_config_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point CONDUCTOR_HOME at a temp directory and return its path."""
+    home = tmp_path / "conductor_home"
+    home.mkdir()
+    monkeypatch.setenv("CONDUCTOR_HOME", str(home))
+    return home
+
+
+SAMPLE_TOML = """\
+default = "official"
+
+[registries.official]
+type = "github"
+source = "microsoft/conductor-workflows"
+
+[registries.local]
+type = "path"
+source = "/Users/jason/workflows"
+"""
+
+
+# ---------------------------------------------------------------------------
+# get_config_path
+# ---------------------------------------------------------------------------
+
+
+class TestGetConfigPath:
+    def test_default_path(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("CONDUCTOR_HOME", raising=False)
+        path = get_config_path()
+        assert path == Path.home() / ".conductor" / "registries.toml"
+
+    def test_conductor_home_override(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("CONDUCTOR_HOME", str(tmp_path / "custom"))
+        path = get_config_path()
+        assert path == tmp_path / "custom" / "registries.toml"
+
+
+# ---------------------------------------------------------------------------
+# load_config
+# ---------------------------------------------------------------------------
+
+
+class TestLoadConfig:
+    def test_missing_file_returns_empty(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = load_config()
+        assert config.default is None
+        assert config.registries == {}
+
+    def test_valid_toml(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        home = _setup_config_home(tmp_path, monkeypatch)
+        (home / "registries.toml").write_text(SAMPLE_TOML)
+
+        config = load_config()
+        assert config.default == "official"
+        assert len(config.registries) == 2
+        assert config.registries["official"].type == RegistryType.github
+        assert config.registries["official"].source == "microsoft/conductor-workflows"
+        assert config.registries["local"].type == RegistryType.path
+        assert config.registries["local"].source == "/Users/jason/workflows"
+
+    def test_malformed_toml_raises(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        home = _setup_config_home(tmp_path, monkeypatch)
+        (home / "registries.toml").write_text("not valid [[[toml")
+
+        with pytest.raises(RegistryError, match="Failed to parse"):
+            load_config()
+
+    def test_invalid_structure_raises(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        home = _setup_config_home(tmp_path, monkeypatch)
+        # default references a registry that doesn't exist
+        (home / "registries.toml").write_text('default = "nope"\n')
+
+        with pytest.raises(RegistryError, match="Invalid registry config"):
+            load_config()
+
+
+# ---------------------------------------------------------------------------
+# save_config / round-trip
+# ---------------------------------------------------------------------------
+
+
+class TestSaveConfig:
+    def test_save_and_reload_roundtrip(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+
+        original = RegistriesConfig(
+            default="team",
+            registries={
+                "team": RegistryEntry(type=RegistryType.github, source="myorg/workflows"),
+                "dev": RegistryEntry(type=RegistryType.path, source="/dev/workflows"),
+            },
+        )
+        save_config(original)
+
+        loaded = load_config()
+        assert loaded.default == "team"
+        assert len(loaded.registries) == 2
+        assert loaded.registries["team"].type == RegistryType.github
+        assert loaded.registries["team"].source == "myorg/workflows"
+        assert loaded.registries["dev"].type == RegistryType.path
+        assert loaded.registries["dev"].source == "/dev/workflows"
+
+    def test_save_creates_parent_dirs(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        deep = tmp_path / "a" / "b" / "c"
+        monkeypatch.setenv("CONDUCTOR_HOME", str(deep))
+
+        save_config(RegistriesConfig())
+        assert (deep / "registries.toml").exists()
+
+    def test_save_empty_config(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        save_config(RegistriesConfig())
+        loaded = load_config()
+        assert loaded.default is None
+        assert loaded.registries == {}
+
+
+# ---------------------------------------------------------------------------
+# add_registry
+# ---------------------------------------------------------------------------
+
+
+class TestAddRegistry:
+    def test_explicit_type(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("myrepo", "some/source", registry_type=RegistryType.github)
+        assert config.registries["myrepo"].type == RegistryType.github
+        assert config.registries["myrepo"].source == "some/source"
+
+    def test_infer_github_type(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("gh", "owner/repo")
+        assert config.registries["gh"].type == RegistryType.github
+
+    def test_infer_path_type(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("local", "/some/path/to/workflows")
+        assert config.registries["local"].type == RegistryType.path
+
+    def test_infer_path_for_absolute(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("abs", "/home/user/my-workflows")
+        assert config.registries["abs"].type == RegistryType.path
+
+    def test_infer_path_for_deep_path(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("deep", "a/b/c")
+        assert config.registries["deep"].type == RegistryType.path
+
+    def test_set_default(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        config = add_registry("main", "org/repo", set_default=True)
+        assert config.default == "main"
+
+    def test_duplicate_name_raises(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("dup", "owner/repo")
+        with pytest.raises(RegistryError, match="already exists"):
+            add_registry("dup", "other/repo")
+
+    def test_persists_to_disk(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("persisted", "org/workflows")
+        loaded = load_config()
+        assert "persisted" in loaded.registries
+
+
+# ---------------------------------------------------------------------------
+# remove_registry
+# ---------------------------------------------------------------------------
+
+
+class TestRemoveRegistry:
+    def test_remove(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("victim", "org/repo")
+        config = remove_registry("victim")
+        assert "victim" not in config.registries
+
+    def test_remove_clears_default(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("main", "org/repo", set_default=True)
+        config = remove_registry("main")
+        assert config.default is None
+
+    def test_remove_preserves_other_default(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("keep", "org/keep", set_default=True)
+        add_registry("drop", "org/drop")
+        config = remove_registry("drop")
+        assert config.default == "keep"
+
+    def test_remove_nonexistent_raises(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        with pytest.raises(RegistryError, match="not found"):
+            remove_registry("ghost")
+
+
+# ---------------------------------------------------------------------------
+# get_registry
+# ---------------------------------------------------------------------------
+
+
+class TestGetRegistry:
+    def test_found(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        add_registry("findme", "org/repo")
+        entry = get_registry("findme")
+        assert entry.type == RegistryType.github
+        assert entry.source == "org/repo"
+
+    def test_not_found_raises(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_config_home(tmp_path, monkeypatch)
+        with pytest.raises(RegistryError, match="not found"):
+            get_registry("nope")
+
+
+# ---------------------------------------------------------------------------
+# RegistriesConfig validation
+# ---------------------------------------------------------------------------
+
+
+class TestRegistriesConfigValidation:
+    def test_default_must_exist_in_registries(self) -> None:
+        with pytest.raises(ValueError, match="not defined in registries"):
+            RegistriesConfig(default="missing", registries={})
+
+    def test_valid_default(self) -> None:
+        config = RegistriesConfig(
+            default="ok",
+            registries={"ok": RegistryEntry(type=RegistryType.github, source="a/b")},
+        )
+        assert config.default == "ok"
+
+    def test_none_default_always_valid(self) -> None:
+        config = RegistriesConfig(default=None, registries={})
+        assert config.default is None
diff --git a/tests/test_registry/test_github.py b/tests/test_registry/test_github.py
new file mode 100644
index 0000000..b89d211
--- /dev/null
+++ b/tests/test_registry/test_github.py
@@ -0,0 +1,168 @@
+"""Tests for conductor.registry.github module."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import httpx
+import pytest
+
+from conductor.registry.errors import RegistryError
+from conductor.registry.github import (
+    fetch_file,
+    fetch_file_text,
+    list_directory,
+    list_tags,
+    parse_github_source,
+)
+
+
+def _mock_response(
+    status_code: int = 200,
+    content: bytes = b"",
+    json_data: object = None,
+) -> MagicMock:
+    """Build a mock httpx.Response."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.is_success = 200 <= status_code < 300
+    resp.content = content
+    if json_data is not None:
+        resp.json.return_value = json_data
+    return resp
+
+
+# --- fetch_file ---
+
+
+class TestFetchFile:
+    @patch("conductor.registry.github.httpx.get")
+    def test_success(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(content=b"hello world")
+        result = fetch_file("owner", "repo", "path/to/file.txt", ref="v1.0")
+
+        assert result == b"hello world"
+        mock_get.assert_called_once()
+        call_args = mock_get.call_args
+        assert "raw.githubusercontent.com/owner/repo/v1.0/path/to/file.txt" in call_args[0][0]
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_404_raises_registry_error(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(status_code=404)
+
+        with pytest.raises(RegistryError, match="not found"):
+            fetch_file("owner", "repo", "missing.txt")
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_timeout_raises_registry_error(self, mock_get: MagicMock) -> None:
+        mock_get.side_effect = httpx.TimeoutException("timed out")
+
+        with pytest.raises(RegistryError, match="Timeout"):
+            fetch_file("owner", "repo", "file.txt")
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_403_rate_limit(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(status_code=403)
+
+        with pytest.raises(RegistryError, match="rate limit"):
+            fetch_file("owner", "repo", "file.txt")
+
+
+# --- fetch_file_text ---
+
+
+class TestFetchFileText:
+    @patch("conductor.registry.github.httpx.get")
+    def test_returns_decoded_string(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(content="café résumé".encode())
+        result = fetch_file_text("owner", "repo", "readme.md")
+
+        assert result == "café résumé"
+        assert isinstance(result, str)
+
+
+# --- list_tags ---
+
+
+class TestListTags:
+    @patch("conductor.registry.github.httpx.get")
+    def test_success(self, mock_get: MagicMock) -> None:
+        tags_json = [{"name": "v2.0"}, {"name": "v1.1"}, {"name": "v1.0"}]
+        mock_get.return_value = _mock_response(json_data=tags_json)
+
+        result = list_tags("owner", "repo")
+
+        assert result == ["v2.0", "v1.1", "v1.0"]
+        call_args = mock_get.call_args
+        assert "api.github.com/repos/owner/repo/tags" in call_args[0][0]
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_error_handling(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(status_code=404)
+
+        with pytest.raises(RegistryError, match="not found"):
+            list_tags("owner", "repo")
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_http_error(self, mock_get: MagicMock) -> None:
+        mock_get.side_effect = httpx.HTTPError("connection failed")
+
+        with pytest.raises(RegistryError, match="HTTP error"):
+            list_tags("owner", "repo")
+
+
+# --- list_directory ---
+
+
+class TestListDirectory:
+    @patch("conductor.registry.github.httpx.get")
+    def test_success(self, mock_get: MagicMock) -> None:
+        contents = [
+            {"name": "workflow.yaml", "type": "file"},
+            {"name": "tools.yaml", "type": "file"},
+            {"name": "subdir", "type": "dir"},
+        ]
+        mock_get.return_value = _mock_response(json_data=contents)
+
+        result = list_directory("owner", "repo", "workflows")
+
+        assert result == ["workflow.yaml", "tools.yaml"]
+        assert "subdir" not in result
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_404_raises_registry_error(self, mock_get: MagicMock) -> None:
+        mock_get.return_value = _mock_response(status_code=404)
+
+        with pytest.raises(RegistryError, match="not found"):
+            list_directory("owner", "repo", "nonexistent")
+
+    @patch("conductor.registry.github.httpx.get")
+    def test_single_file_raises_error(self, mock_get: MagicMock) -> None:
+        # Contents API returns a single object (not a list) when path is a file
+        mock_get.return_value = _mock_response(json_data={"name": "file.txt", "type": "file"})
+
+        with pytest.raises(RegistryError, match="Expected a directory"):
+            list_directory("owner", "repo", "file.txt")
+
+
+# --- parse_github_source ---
+
+
+class TestParseGithubSource:
+    def test_valid(self) -> None:
+        assert parse_github_source("microsoft/conductor") == ("microsoft", "conductor")
+
+    def test_invalid_no_slash(self) -> None:
+        with pytest.raises(RegistryError, match="Invalid GitHub source"):
+            parse_github_source("just-a-name")
+
+    def test_invalid_too_many_parts(self) -> None:
+        with pytest.raises(RegistryError, match="Invalid GitHub source"):
+            parse_github_source("a/b/c")
+
+    def test_invalid_empty_parts(self) -> None:
+        with pytest.raises(RegistryError, match="Invalid GitHub source"):
+            parse_github_source("/repo")
+
+        with pytest.raises(RegistryError, match="Invalid GitHub source"):
+            parse_github_source("owner/")
diff --git a/tests/test_registry/test_index.py b/tests/test_registry/test_index.py
new file mode 100644
index 0000000..416f344
--- /dev/null
+++ b/tests/test_registry/test_index.py
@@ -0,0 +1,328 @@
+"""Tests for registry index loading and parsing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from ruamel.yaml import YAML
+
+from conductor.registry.config import RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+from conductor.registry.index import (
+    RegistryIndex,
+    WorkflowInfo,
+    get_workflow_info,
+    load_index,
+    resolve_latest,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_SAMPLE_INDEX: dict = {
+    "workflows": {
+        "qa-bot": {
+            "description": "Simple Q&A workflow",
+            "path": "workflows/qa-bot.yaml",
+            "versions": ["1.0.0", "1.1.0", "2.0.0"],
+        },
+        "code-review": {
+            "description": "Multi-agent code review",
+            "path": "workflows/code-review.yaml",
+            "versions": ["0.3.0"],
+        },
+    }
+}
+
+
+def _write_yaml(path: Path, data: dict) -> None:
+    yaml = YAML(typ="safe")
+    with open(path, "w") as f:
+        yaml.dump(data, f)
+
+
+def _write_json(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def _path_entry(source: str) -> RegistryEntry:
+    return RegistryEntry(type=RegistryType.path, source=source)
+
+
+def _github_entry(source: str = "owner/repo") -> RegistryEntry:
+    return RegistryEntry(type=RegistryType.github, source=source)
+
+
+def _make_response(status_code: int = 200, text: str = "") -> MagicMock:
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.text = text
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Tests: load_index — local path registries
+# ---------------------------------------------------------------------------
+
+
+class TestLoadPathIndex:
+    """Tests for loading index from local path registries."""
+
+    def test_load_yaml(self, tmp_path: Path) -> None:
+        """index.yaml is loaded and parsed correctly."""
+        _write_yaml(tmp_path / "index.yaml", _SAMPLE_INDEX)
+        idx = load_index(_path_entry(str(tmp_path)))
+
+        assert "qa-bot" in idx.workflows
+        assert "code-review" in idx.workflows
+        assert idx.workflows["qa-bot"].description == "Simple Q&A workflow"
+        assert idx.workflows["qa-bot"].path == "workflows/qa-bot.yaml"
+        assert idx.workflows["qa-bot"].versions == ["1.0.0", "1.1.0", "2.0.0"]
+
+    def test_load_json_fallback(self, tmp_path: Path) -> None:
+        """index.json is loaded when index.yaml does not exist."""
+        _write_json(tmp_path / "index.json", _SAMPLE_INDEX)
+        idx = load_index(_path_entry(str(tmp_path)))
+
+        assert "qa-bot" in idx.workflows
+        assert idx.workflows["code-review"].versions == ["0.3.0"]
+
+    def test_yaml_preferred_over_json(self, tmp_path: Path) -> None:
+        """index.yaml takes priority when both files exist."""
+        yaml_data = {
+            "workflows": {
+                "from-yaml": {
+                    "description": "from yaml",
+                    "path": "workflows/yaml.yaml",
+                }
+            }
+        }
+        json_data = {
+            "workflows": {
+                "from-json": {
+                    "description": "from json",
+                    "path": "workflows/json.yaml",
+                }
+            }
+        }
+        _write_yaml(tmp_path / "index.yaml", yaml_data)
+        _write_json(tmp_path / "index.json", json_data)
+
+        idx = load_index(_path_entry(str(tmp_path)))
+        assert "from-yaml" in idx.workflows
+        assert "from-json" not in idx.workflows
+
+    def test_missing_index_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised when neither index file exists."""
+        with pytest.raises(RegistryError, match="No index.yaml or index.json"):
+            load_index(_path_entry(str(tmp_path)))
+
+    def test_nonexistent_directory_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised when the source dir does not exist."""
+        with pytest.raises(RegistryError, match="does not exist"):
+            load_index(_path_entry(str(tmp_path / "nope")))
+
+    def test_malformed_yaml_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised for invalid YAML content."""
+        (tmp_path / "index.yaml").write_text("a: [unterminated", encoding="utf-8")
+        with pytest.raises(RegistryError, match="Failed to parse"):
+            load_index(_path_entry(str(tmp_path)))
+
+    def test_malformed_json_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised for invalid JSON content."""
+        (tmp_path / "index.json").write_text("{bad json", encoding="utf-8")
+        with pytest.raises(RegistryError, match="Failed to parse"):
+            load_index(_path_entry(str(tmp_path)))
+
+    def test_malformed_schema_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised when data doesn't match expected schema."""
+        # workflows entries missing required 'path' field
+        bad_data = {"workflows": {"broken": {"description": "no path"}}}
+        _write_yaml(tmp_path / "index.yaml", bad_data)
+        with pytest.raises(RegistryError, match="Malformed"):
+            load_index(_path_entry(str(tmp_path)))
+
+    def test_non_mapping_yaml_raises(self, tmp_path: Path) -> None:
+        """RegistryError raised when YAML top level is not a mapping."""
+        (tmp_path / "index.yaml").write_text("- just\n- a\n- list\n", encoding="utf-8")
+        with pytest.raises(RegistryError, match="expected a mapping"):
+            load_index(_path_entry(str(tmp_path)))
+
+    def test_empty_workflows(self, tmp_path: Path) -> None:
+        """An index with no workflows is valid."""
+        _write_yaml(tmp_path / "index.yaml", {"workflows": {}})
+        idx = load_index(_path_entry(str(tmp_path)))
+        assert idx.workflows == {}
+
+
+# ---------------------------------------------------------------------------
+# Tests: load_index — GitHub registries
+# ---------------------------------------------------------------------------
+
+
+class TestLoadGitHubIndex:
+    """Tests for loading index from GitHub registries."""
+
+    @patch("conductor.registry.index.httpx.get")
+    def test_fetch_yaml_main(self, mock_get: MagicMock) -> None:
+        """Fetches index.yaml from main branch."""
+        yaml = YAML(typ="safe")
+        from io import StringIO
+
+        stream = StringIO()
+        yaml.dump(_SAMPLE_INDEX, stream)
+        yaml_text = stream.getvalue()
+
+        mock_get.return_value = _make_response(200, yaml_text)
+
+        idx = load_index(_github_entry("myorg/myrepo"))
+        assert "qa-bot" in idx.workflows
+
+        mock_get.assert_called_once()
+        call_url = mock_get.call_args[0][0]
+        assert "myorg/myrepo/main/index.yaml" in call_url
+
+    @patch("conductor.registry.index.httpx.get")
+    def test_fallback_to_master(self, mock_get: MagicMock) -> None:
+        """Falls back to master branch when main returns 404."""
+        yaml = YAML(typ="safe")
+        from io import StringIO
+
+        stream = StringIO()
+        yaml.dump(_SAMPLE_INDEX, stream)
+        yaml_text = stream.getvalue()
+
+        # main returns 404, master returns 200
+        mock_get.side_effect = [
+            _make_response(404),
+            _make_response(200, yaml_text),
+        ]
+
+        idx = load_index(_github_entry("myorg/myrepo"))
+        assert "qa-bot" in idx.workflows
+        assert mock_get.call_count == 2
+
+        # First call was main, second was master
+        calls = [c[0][0] for c in mock_get.call_args_list]
+        assert "main/index.yaml" in calls[0]
+        assert "master/index.yaml" in calls[1]
+
+    @patch("conductor.registry.index.httpx.get")
+    def test_fallback_to_json(self, mock_get: MagicMock) -> None:
+        """Falls back to index.json when index.yaml not found on any branch."""
+        json_text = json.dumps(_SAMPLE_INDEX)
+
+        # yaml on main → 404, yaml on master → 404, json on main → 200
+        mock_get.side_effect = [
+            _make_response(404),
+            _make_response(404),
+            _make_response(200, json_text),
+        ]
+
+        idx = load_index(_github_entry("myorg/myrepo"))
+        assert "qa-bot" in idx.workflows
+        assert mock_get.call_count == 3
+
+        calls = [c[0][0] for c in mock_get.call_args_list]
+        assert "index.json" in calls[2]
+
+    @patch("conductor.registry.index.httpx.get")
+    def test_all_404_raises(self, mock_get: MagicMock) -> None:
+        """RegistryError when all fetch attempts return 404."""
+        mock_get.return_value = _make_response(404)
+
+        with pytest.raises(RegistryError, match="No index.yaml or index.json"):
+            load_index(_github_entry("myorg/myrepo"))
+
+        # yaml(main, master) + json(main, master) = 4 attempts
+        assert mock_get.call_count == 4
+
+    @patch("conductor.registry.index.httpx.get")
+    def test_network_error_raises(self, mock_get: MagicMock) -> None:
+        """RegistryError on network failure."""
+        import httpx as _httpx
+
+        mock_get.side_effect = _httpx.ConnectError("connection refused")
+
+        with pytest.raises(RegistryError, match="Failed to fetch"):
+            load_index(_github_entry("myorg/myrepo"))
+
+
+# ---------------------------------------------------------------------------
+# Tests: resolve_latest
+# ---------------------------------------------------------------------------
+
+
+class TestResolveLatest:
+    """Tests for resolve_latest."""
+
+    def test_returns_last_version(self) -> None:
+        """Returns the last version in the list."""
+        idx = RegistryIndex(
+            workflows={
+                "wf": WorkflowInfo(path="w.yaml", versions=["1.0.0", "1.1.0", "2.0.0"]),
+            }
+        )
+        assert resolve_latest(idx, "wf") == "2.0.0"
+
+    def test_single_version(self) -> None:
+        """Works with a single version."""
+        idx = RegistryIndex(
+            workflows={
+                "wf": WorkflowInfo(path="w.yaml", versions=["0.1.0"]),
+            }
+        )
+        assert resolve_latest(idx, "wf") == "0.1.0"
+
+    def test_no_versions_raises(self) -> None:
+        """RegistryError when the workflow has no versions."""
+        idx = RegistryIndex(
+            workflows={
+                "wf": WorkflowInfo(path="w.yaml", versions=[]),
+            }
+        )
+        with pytest.raises(RegistryError, match="no versions"):
+            resolve_latest(idx, "wf")
+
+    def test_workflow_not_found_raises(self) -> None:
+        """RegistryError when the workflow doesn't exist."""
+        idx = RegistryIndex(workflows={})
+        with pytest.raises(RegistryError, match="not found"):
+            resolve_latest(idx, "nope")
+
+
+# ---------------------------------------------------------------------------
+# Tests: get_workflow_info
+# ---------------------------------------------------------------------------
+
+
+class TestGetWorkflowInfo:
+    """Tests for get_workflow_info."""
+
+    def test_found(self) -> None:
+        """Returns WorkflowInfo for an existing workflow."""
+        info = WorkflowInfo(description="My workflow", path="workflows/my.yaml", versions=["1.0.0"])
+        idx = RegistryIndex(workflows={"my-wf": info})
+
+        result = get_workflow_info(idx, "my-wf")
+        assert result.description == "My workflow"
+        assert result.path == "workflows/my.yaml"
+        assert result.versions == ["1.0.0"]
+
+    def test_not_found_raises(self) -> None:
+        """RegistryError when the workflow is not in the index."""
+        idx = RegistryIndex(
+            workflows={
+                "alpha": WorkflowInfo(path="a.yaml"),
+                "beta": WorkflowInfo(path="b.yaml"),
+            }
+        )
+        with pytest.raises(RegistryError, match="not found") as exc_info:
+            get_workflow_info(idx, "gamma")
+        # Suggestion lists available workflows
+        assert "alpha" in str(exc_info.value.suggestion)
+        assert "beta" in str(exc_info.value.suggestion)
diff --git a/tests/test_registry/test_integration.py b/tests/test_registry/test_integration.py
new file mode 100644
index 0000000..98029e7
--- /dev/null
+++ b/tests/test_registry/test_integration.py
@@ -0,0 +1,469 @@
+"""Integration tests for the registry system.
+
+Tests the full flow: configure registry → resolve ref → fetch workflow → get cached path.
+Uses local path registries to avoid network dependencies.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from conductor.cli.app import app
+from conductor.registry.cache import fetch_workflow, get_cached_workflow_path
+from conductor.registry.config import (
+    RegistryType,
+    add_registry,
+    load_config,
+    remove_registry,
+)
+from conductor.registry.resolver import resolve_ref
+
+runner = CliRunner()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _setup_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Point CONDUCTOR_HOME at a temp directory and return its path."""
+    home = tmp_path / "conductor_home"
+    home.mkdir()
+    monkeypatch.setenv("CONDUCTOR_HOME", str(home))
+    return home
+
+
+def _create_local_registry(
+    root: Path,
+    workflows: dict[str, dict],
+    *,
+    sibling_files: dict[str, dict[str, str]] | None = None,
+) -> Path:
+    """Build a minimal local registry directory.
+
+    Args:
+        root: Parent directory (e.g. tmp_path).
+        workflows: Mapping of workflow-name → dict with keys
+            ``description``, ``path``, ``versions``, and ``content``
+            (the YAML text of the workflow file).
+        sibling_files: Optional mapping of workflow-name → dict of
+            filename → content for extra files alongside the workflow.
+
+    Returns:
+        Path to the registry root directory.
+    """
+    from ruamel.yaml import YAML
+
+    registry_dir = root / "registry"
+    registry_dir.mkdir(parents=True, exist_ok=True)
+
+    # Build index.yaml
+    index_data: dict = {"workflows": {}}
+    for name, info in workflows.items():
+        index_data["workflows"][name] = {
+            "description": info.get("description", ""),
+            "path": info["path"],
+            "versions": info.get("versions", []),
+        }
+
+        # Write the workflow file
+        wf_path = registry_dir / info["path"]
+        wf_path.parent.mkdir(parents=True, exist_ok=True)
+        wf_path.write_text(info["content"])
+
+        # Write sibling files
+        if sibling_files and name in sibling_files:
+            for fname, fcontent in sibling_files[name].items():
+                (wf_path.parent / fname).write_text(fcontent)
+
+    yaml = YAML()
+    with open(registry_dir / "index.yaml", "w") as f:
+        yaml.dump(index_data, f)
+
+    return registry_dir
+
+
+_SIMPLE_WORKFLOW = """\
+name: test-workflow
+agents:
+  helper:
+    model: copilot
+    instructions: Say hello
+steps:
+  - agent: helper
+"""
+
+
+# ---------------------------------------------------------------------------
+# Full local registry flow
+# ---------------------------------------------------------------------------
+
+
+class TestFullLocalFlow:
+    """Configure → resolve → fetch → verify cached content."""
+
+    def test_local_registry_end_to_end(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "hello": {
+                    "description": "A greeting workflow",
+                    "path": "hello/workflow.yaml",
+                    "versions": ["1.0.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        # Add registry
+        add_registry("my-reg", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+
+        # Resolve with explicit registry and version
+        ref = resolve_ref("hello@my-reg@1.0.0")
+        assert ref.kind == "registry"
+        assert ref.workflow == "hello"
+        assert ref.registry_name == "my-reg"
+        assert ref.version == "1.0.0"
+        assert ref.registry_entry is not None
+
+        # Fetch
+        cached_path = fetch_workflow("my-reg", ref.registry_entry, "hello", version="1.0.0")
+        assert cached_path.exists()
+        assert cached_path.name == "workflow.yaml"
+        assert "test-workflow" in cached_path.read_text()
+
+
+# ---------------------------------------------------------------------------
+# Default registry flow
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultRegistryFlow:
+    """Resolve using the default registry (no @registry in ref)."""
+
+    def test_resolve_via_default(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "greeter": {
+                    "description": "Greet someone",
+                    "path": "greeter.yaml",
+                    "versions": ["0.1.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        add_registry("default-reg", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+
+        # Resolve without @registry — should use default
+        ref = resolve_ref("greeter")
+        assert ref.kind == "registry"
+        assert ref.registry_name == "default-reg"
+        assert ref.workflow == "greeter"
+
+        # Fetch and verify
+        cached = fetch_workflow("default-reg", ref.registry_entry, "greeter", version="0.1.0")
+        assert cached.exists()
+        assert "test-workflow" in cached.read_text()
+
+
+# ---------------------------------------------------------------------------
+# Latest version resolution
+# ---------------------------------------------------------------------------
+
+
+class TestLatestVersionResolution:
+    """When no version is specified, the last version in the list is used."""
+
+    def test_resolves_latest_version(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "multi-ver": {
+                    "description": "Has multiple versions",
+                    "path": "multi-ver.yaml",
+                    "versions": ["1.0.0", "1.1.0", "2.0.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        add_registry("ver-reg", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+
+        # Fetch without version — should resolve to 2.0.0 (last in list)
+        ref = resolve_ref("multi-ver")
+        assert ref.registry_entry is not None
+
+        cached = fetch_workflow("ver-reg", ref.registry_entry, "multi-ver")
+        assert cached.exists()
+
+        # The cache directory should be under the "2.0.0" version folder
+        assert "2.0.0" in str(cached)
+
+
+# ---------------------------------------------------------------------------
+# Cache reuse
+# ---------------------------------------------------------------------------
+
+
+class TestCacheReuse:
+    """Second fetch of the same ref returns the cached path without re-copying."""
+
+    def test_second_fetch_returns_cached(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "cached-wf": {
+                    "description": "Cached workflow",
+                    "path": "cached-wf.yaml",
+                    "versions": ["1.0.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        add_registry("cache-reg", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+        ref = resolve_ref("cached-wf")
+        assert ref.registry_entry is not None
+
+        # First fetch
+        path1 = fetch_workflow("cache-reg", ref.registry_entry, "cached-wf", version="1.0.0")
+
+        # Second fetch — should return the same cached path
+        path2 = fetch_workflow("cache-reg", ref.registry_entry, "cached-wf", version="1.0.0")
+
+        assert path1 == path2
+        assert path1.exists()
+
+        # Also verify via the direct cache lookup API
+        cached = get_cached_workflow_path("cache-reg", "cached-wf", "1.0.0")
+        assert cached == path1
+
+
+# ---------------------------------------------------------------------------
+# Sibling files
+# ---------------------------------------------------------------------------
+
+
+class TestSiblingFiles:
+    """Sibling files in the workflow directory are also cached."""
+
+    def test_siblings_copied_to_cache(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "with-siblings": {
+                    "description": "Has extra files",
+                    "path": "with-siblings/workflow.yaml",
+                    "versions": ["1.0.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+            sibling_files={
+                "with-siblings": {
+                    "prompt.txt": "You are a helpful assistant.",
+                    "schema.json": '{"type": "object"}',
+                },
+            },
+        )
+
+        add_registry("sib-reg", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+        ref = resolve_ref("with-siblings")
+        assert ref.registry_entry is not None
+
+        cached = fetch_workflow("sib-reg", ref.registry_entry, "with-siblings", version="1.0.0")
+        cache_dir = cached.parent
+
+        # Siblings should be in the same directory as the workflow
+        assert (cache_dir / "prompt.txt").exists()
+        assert (cache_dir / "prompt.txt").read_text() == "You are a helpful assistant."
+        assert (cache_dir / "schema.json").exists()
+        assert (cache_dir / "schema.json").read_text() == '{"type": "object"}'
+
+
+# ---------------------------------------------------------------------------
+# CLI round-trip
+# ---------------------------------------------------------------------------
+
+
+class TestCLIRoundTrip:
+    """Exercise the CLI commands for add → list → list <name> → remove."""
+
+    @pytest.fixture(autouse=True)
+    def _isolate(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        _setup_home(tmp_path, monkeypatch)
+        self._tmp_path = tmp_path
+
+    def test_full_cli_lifecycle(self) -> None:
+        # Create a local registry on disk
+        reg_dir = _create_local_registry(
+            self._tmp_path,
+            {
+                "demo": {
+                    "description": "Demo workflow",
+                    "path": "demo.yaml",
+                    "versions": ["1.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        # Add registry with --default
+        result = runner.invoke(
+            app, ["registry", "add", "test-reg", str(reg_dir), "--type", "path", "--default"]
+        )
+        assert result.exit_code == 0, result.output
+        assert "added" in result.output
+
+        # List registries — should show test-reg
+        result = runner.invoke(app, ["registry", "list"])
+        assert result.exit_code == 0, result.output
+        assert "test-reg" in result.output
+        assert "✓" in result.output  # default marker
+
+        # List workflows in test-reg
+        result = runner.invoke(app, ["registry", "list", "test-reg"])
+        assert result.exit_code == 0, result.output
+        assert "demo" in result.output
+        assert "Demo workflow" in result.output
+
+        # Remove registry
+        result = runner.invoke(app, ["registry", "remove", "test-reg"])
+        assert result.exit_code == 0, result.output
+        assert "removed" in result.output
+
+        # List again — should be empty
+        result = runner.invoke(app, ["registry", "list"])
+        assert result.exit_code == 0, result.output
+        assert "No registries configured" in result.output
+
+    def test_add_list_remove_multiple(self) -> None:
+        """Add two registries, list both, remove one, verify the other remains."""
+        reg1 = _create_local_registry(
+            self._tmp_path / "r1_parent",
+            {
+                "wf-a": {
+                    "description": "A",
+                    "path": "a.yaml",
+                    "versions": ["1.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+        reg2 = _create_local_registry(
+            self._tmp_path / "r2_parent",
+            {
+                "wf-b": {
+                    "description": "B",
+                    "path": "b.yaml",
+                    "versions": ["2.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        runner.invoke(app, ["registry", "add", "reg-a", str(reg1), "--type", "path"])
+        runner.invoke(app, ["registry", "add", "reg-b", str(reg2), "--type", "path"])
+
+        result = runner.invoke(app, ["registry", "list"])
+        assert "reg-a" in result.output
+        assert "reg-b" in result.output
+
+        runner.invoke(app, ["registry", "remove", "reg-a"])
+
+        result = runner.invoke(app, ["registry", "list"])
+        assert "reg-a" not in result.output
+        assert "reg-b" in result.output
+
+    def test_set_default_and_resolve(self) -> None:
+        """Set a default registry and resolve a bare workflow name."""
+        reg_dir = _create_local_registry(
+            self._tmp_path,
+            {
+                "auto": {
+                    "description": "Auto-resolved",
+                    "path": "auto.yaml",
+                    "versions": ["1.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        runner.invoke(app, ["registry", "add", "def-reg", str(reg_dir), "--type", "path"])
+        runner.invoke(app, ["registry", "set-default", "def-reg"])
+
+        # Verify config
+        config = load_config()
+        assert config.default == "def-reg"
+
+        # Resolve bare name (no @)
+        ref = resolve_ref("auto")
+        assert ref.kind == "registry"
+        assert ref.registry_name == "def-reg"
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    """Additional edge-case coverage for the integration flow."""
+
+    def test_remove_default_clears_it(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Removing the default registry clears the default setting."""
+        _setup_home(tmp_path, monkeypatch)
+
+        reg_dir = _create_local_registry(
+            tmp_path,
+            {
+                "wf": {
+                    "description": "",
+                    "path": "wf.yaml",
+                    "versions": ["1.0"],
+                    "content": _SIMPLE_WORKFLOW,
+                },
+            },
+        )
+
+        add_registry("gone", str(reg_dir), registry_type=RegistryType.path, set_default=True)
+        assert load_config().default == "gone"
+
+        remove_registry("gone")
+        assert load_config().default is None
+
+    def test_file_path_takes_precedence_over_registry(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """An existing file on disk resolves as 'file', not 'registry'."""
+        _setup_home(tmp_path, monkeypatch)
+
+        local_file = tmp_path / "my-workflow.yaml"
+        local_file.write_text(_SIMPLE_WORKFLOW)
+
+        ref = resolve_ref(str(local_file))
+        assert ref.kind == "file"
+        assert ref.path == local_file
diff --git a/tests/test_registry/test_resolver.py b/tests/test_registry/test_resolver.py
new file mode 100644
index 0000000..b028868
--- /dev/null
+++ b/tests/test_registry/test_resolver.py
@@ -0,0 +1,216 @@
+"""Tests for conductor.registry.resolver."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from conductor.registry.config import RegistriesConfig, RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+from conductor.registry.resolver import ResolvedRef, _looks_like_file_path, resolve_ref
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _patch_config(monkeypatch: pytest.MonkeyPatch, config: RegistriesConfig) -> None:
+    """Monkey-patch ``load_config`` to return *config*."""
+    monkeypatch.setattr(
+        "conductor.registry.resolver.load_config",
+        lambda: config,
+    )
+
+
+def _make_config(
+    *,
+    default: str | None = None,
+    registries: dict[str, RegistryEntry] | None = None,
+) -> RegistriesConfig:
+    if registries is None:
+        registries = {
+            "team": RegistryEntry(type=RegistryType.github, source="acme/workflows"),
+            "local": RegistryEntry(type=RegistryType.path, source="/opt/workflows"),
+        }
+    return RegistriesConfig(default=default, registries=registries)
+
+
+# ---------------------------------------------------------------------------
+# ResolvedRef dataclass
+# ---------------------------------------------------------------------------
+
+
+class TestResolvedRef:
+    """Basic sanity checks for the frozen dataclass."""
+
+    def test_file_ref_fields(self) -> None:
+        ref = ResolvedRef(kind="file", path=Path("my.yaml"))
+        assert ref.kind == "file"
+        assert ref.path == Path("my.yaml")
+        assert ref.workflow is None
+        assert ref.registry_name is None
+        assert ref.version is None
+        assert ref.registry_entry is None
+
+    def test_registry_ref_fields(self) -> None:
+        entry = RegistryEntry(type=RegistryType.github, source="o/r")
+        ref = ResolvedRef(
+            kind="registry",
+            workflow="qa-bot",
+            registry_name="team",
+            version="1.2.3",
+            registry_entry=entry,
+        )
+        assert ref.kind == "registry"
+        assert ref.workflow == "qa-bot"
+        assert ref.registry_name == "team"
+        assert ref.version == "1.2.3"
+        assert ref.registry_entry is entry
+
+    def test_frozen(self) -> None:
+        ref = ResolvedRef(kind="file", path=Path("a.yaml"))
+        with pytest.raises(AttributeError):
+            ref.kind = "registry"  # type: ignore[misc]
+
+
+# ---------------------------------------------------------------------------
+# _looks_like_file_path
+# ---------------------------------------------------------------------------
+
+
+class TestLooksLikeFilePath:
+    def test_forward_slash(self) -> None:
+        assert _looks_like_file_path("./my-workflow.yaml") is True
+        assert _looks_like_file_path("dir/workflow") is True
+
+    def test_backslash(self) -> None:
+        assert _looks_like_file_path("dir\\workflow.yaml") is True
+
+    def test_yaml_extension(self) -> None:
+        assert _looks_like_file_path("my-workflow.yaml") is True
+        assert _looks_like_file_path("my-workflow.yml") is True
+        assert _looks_like_file_path("MY-WORKFLOW.YAML") is True
+
+    def test_existing_file(self, tmp_path: Path) -> None:
+        f = tmp_path / "wf"
+        f.write_text("hello")
+        assert _looks_like_file_path(str(f)) is True
+
+    def test_plain_name_not_file(self) -> None:
+        assert _looks_like_file_path("qa-bot") is False
+
+
+# ---------------------------------------------------------------------------
+# resolve_ref — file paths
+# ---------------------------------------------------------------------------
+
+
+class TestResolveRefFile:
+    def test_existing_file_on_disk(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        f = tmp_path / "workflow"
+        f.write_text("content")
+        ref = resolve_ref(str(f))
+        assert ref.kind == "file"
+        assert ref.path == Path(str(f))
+
+    def test_yaml_extension_nonexistent(self) -> None:
+        ref = resolve_ref("nonexistent.yaml")
+        assert ref.kind == "file"
+        assert ref.path == Path("nonexistent.yaml")
+
+    def test_yml_extension_nonexistent(self) -> None:
+        ref = resolve_ref("nonexistent.yml")
+        assert ref.kind == "file"
+        assert ref.path == Path("nonexistent.yml")
+
+    def test_path_with_slash(self) -> None:
+        ref = resolve_ref("./my-workflow.yaml")
+        assert ref.kind == "file"
+        assert ref.path == Path("./my-workflow.yaml")
+
+    def test_path_with_backslash(self) -> None:
+        ref = resolve_ref("dir\\workflow")
+        assert ref.kind == "file"
+        assert ref.path == Path("dir\\workflow")
+
+
+# ---------------------------------------------------------------------------
+# resolve_ref — registry references
+# ---------------------------------------------------------------------------
+
+
+class TestResolveRefRegistry:
+    def test_name_only_uses_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        ref = resolve_ref("qa-bot")
+        assert ref.kind == "registry"
+        assert ref.workflow == "qa-bot"
+        assert ref.registry_name == "team"
+        assert ref.version is None
+        assert ref.registry_entry == config.registries["team"]
+
+    def test_name_at_registry(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        ref = resolve_ref("qa-bot@local")
+        assert ref.kind == "registry"
+        assert ref.workflow == "qa-bot"
+        assert ref.registry_name == "local"
+        assert ref.version is None
+        assert ref.registry_entry == config.registries["local"]
+
+    def test_name_at_registry_at_version(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        ref = resolve_ref("qa-bot@team@1.2.3")
+        assert ref.kind == "registry"
+        assert ref.workflow == "qa-bot"
+        assert ref.registry_name == "team"
+        assert ref.version == "1.2.3"
+
+    def test_name_at_empty_at_version_uses_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        ref = resolve_ref("qa-bot@@1.2.3")
+        assert ref.kind == "registry"
+        assert ref.workflow == "qa-bot"
+        assert ref.registry_name == "team"
+        assert ref.version == "1.2.3"
+
+    def test_missing_default_raises(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default=None)
+        _patch_config(monkeypatch, config)
+
+        with pytest.raises(RegistryError, match="No default registry configured"):
+            resolve_ref("qa-bot")
+
+    def test_missing_default_with_empty_registry_raises(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        config = _make_config(default=None)
+        _patch_config(monkeypatch, config)
+
+        with pytest.raises(RegistryError, match="No default registry configured"):
+            resolve_ref("qa-bot@@1.0.0")
+
+    def test_unknown_registry_raises(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        with pytest.raises(RegistryError, match="Registry 'nope' not found"):
+            resolve_ref("qa-bot@nope")
+
+    def test_registry_entry_populated(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        config = _make_config(default="team")
+        _patch_config(monkeypatch, config)
+
+        ref = resolve_ref("qa-bot@team@2.0.0")
+        assert ref.registry_entry is not None
+        assert ref.registry_entry.type == RegistryType.github
+        assert ref.registry_entry.source == "acme/workflows"
diff --git a/uv.lock b/uv.lock
index edeea75..d74e9be 100644
--- a/uv.lock
+++ b/uv.lock
@@ -156,6 +156,7 @@ dependencies = [
     { name = "anthropic" },
     { name = "fastapi" },
     { name = "github-copilot-sdk" },
+    { name = "httpx" },
     { name = "jinja2" },
     { name = "mcp" },
     { name = "pydantic" },
@@ -181,6 +182,7 @@ requires-dist = [
     { name = "anthropic", specifier = ">=0.77.0,<1.0.0" },
     { name = "fastapi", specifier = ">=0.115.0" },
     { name = "github-copilot-sdk", specifier = ">=0.2.0" },
+    { name = "httpx", specifier = ">=0.27.0" },
     { name = "jinja2", specifier = ">=3.1.0" },
     { name = "mcp", specifier = ">=1.0.0" },
     { name = "pydantic", specifier = ">=2.0.0" },

From 39732c984caa894ebbc3dec689fc4517c3ee40f6 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 08:30:47 -0400
Subject: [PATCH 02/13] fix(registry): add type narrowing asserts for
 ResolvedRef fields

The type checker flags `ref.workflow`, `ref.registry_name`, and
`ref.registry_entry` as `str | None` when passed to functions
expecting non-optional args. Add assert narrowing in each branch
to satisfy the type checker.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/app.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py
index 9f53c73..3ddf6b5 100644
--- a/src/conductor/cli/app.py
+++ b/src/conductor/cli/app.py
@@ -327,8 +327,12 @@ def run(
     try:
         ref = resolve_ref(workflow)
         if ref.kind == "file":
+            assert ref.path is not None
             workflow_path = ref.path
         else:
+            assert ref.registry_name is not None
+            assert ref.registry_entry is not None
+            assert ref.workflow is not None
             workflow_path = fetch_registry_workflow(
                 registry_name=ref.registry_name,
                 registry_entry=ref.registry_entry,
@@ -459,8 +463,12 @@ def validate(
     try:
         ref = resolve_ref(workflow)
         if ref.kind == "file":
+            assert ref.path is not None
             workflow_path = ref.path
         else:
+            assert ref.registry_name is not None
+            assert ref.registry_entry is not None
+            assert ref.workflow is not None
             workflow_path = fetch_registry_workflow(
                 registry_name=ref.registry_name,
                 registry_entry=ref.registry_entry,
@@ -572,6 +580,7 @@ def resume(
         try:
             ref = resolve_ref(workflow)
             if ref.kind == "file":
+                assert ref.path is not None
                 resolved_workflow = ref.path.resolve()
                 if not resolved_workflow.exists():
                     console.print(
@@ -579,6 +588,9 @@ def resume(
                     )
                     raise typer.Exit(code=1)
             else:
+                assert ref.registry_name is not None
+                assert ref.registry_entry is not None
+                assert ref.workflow is not None
                 resolved_workflow = fetch_registry_workflow(
                     registry_name=ref.registry_name,
                     registry_entry=ref.registry_entry,

From accb2703e382769844579f4e876a797c64d15b10 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 08:51:40 -0400
Subject: [PATCH 03/13] feat(registry): auto-set first registry as default

When adding the first registry (no default configured yet), it is
automatically set as the default. Subsequent registries still require
--default to change the default.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/registry/config.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/conductor/registry/config.py b/src/conductor/registry/config.py
index 39d52fa..16c65e6 100644
--- a/src/conductor/registry/config.py
+++ b/src/conductor/registry/config.py
@@ -173,6 +173,9 @@ def add_registry(
 ) -> RegistriesConfig:
     """Add a new registry entry and persist the config.
 
+    If this is the first registry being added (no default is set), it is
+    automatically set as the default.
+
     Args:
         name: Unique name for the registry.
         source: Location — ``owner/repo`` for github, filesystem path for path.
@@ -196,7 +199,7 @@ def add_registry(
     resolved_type = registry_type if registry_type is not None else _infer_type(source)
 
     config.registries[name] = RegistryEntry(type=resolved_type, source=source)
-    if set_default:
+    if set_default or config.default is None:
         config.default = name
 
     save_config(config)

From 56b1e43d317f28d2ec0c2a82c56289182c71bfdf Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 08:53:51 -0400
Subject: [PATCH 04/13] feat(registry): add GitHub auth via gh CLI for private
 repos

GitHub fetch helpers now automatically pick up a token from
`gh auth token` when available, enabling access to private
registry repos. Falls back to unauthenticated requests for
public repos.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/registry/github.py | 49 ++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/src/conductor/registry/github.py b/src/conductor/registry/github.py
index a0dfde5..9c56237 100644
--- a/src/conductor/registry/github.py
+++ b/src/conductor/registry/github.py
@@ -1,7 +1,13 @@
-"""Helpers for fetching files, tags, and directory contents from public GitHub repos."""
+"""Helpers for fetching files, tags, and directory contents from GitHub repos.
+
+Supports both public and private repos. Authentication is resolved
+automatically via the ``gh`` CLI (``gh auth token``) when available.
+"""
 
 from __future__ import annotations
 
+import subprocess
+
 import httpx
 
 from conductor.registry.errors import RegistryError
@@ -17,6 +23,36 @@
 }
 
 
+def _get_auth_token() -> str | None:
+    """Attempt to get a GitHub token from the ``gh`` CLI.
+
+    Returns:
+        A token string, or ``None`` if the ``gh`` CLI is not available or
+        not authenticated.
+    """
+    try:
+        result = subprocess.run(  # noqa: S603, S607
+            ["gh", "auth", "token"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def _build_headers(*, api: bool = False) -> dict[str, str]:
+    """Build request headers, adding auth if a token is available."""
+    base = dict(_API_HEADERS if api else _HEADERS)
+    token = _get_auth_token()
+    if token:
+        base["Authorization"] = f"Bearer {token}"
+    return base
+
+
 def _raise_for_status(response: httpx.Response, *, context: str) -> None:
     """Check response status and raise RegistryError with helpful messages."""
     if response.is_success:
@@ -24,7 +60,8 @@ def _raise_for_status(response: httpx.Response, *, context: str) -> None:
     status = response.status_code
     if status == 404:
         raise RegistryError(
-            f"{context}: not found (404). Check that the repository is public and the ref exists."
+            f"{context}: not found (404). Check that the repository exists and the ref is valid.",
+            suggestion="If this is a private repo, ensure 'gh auth login' has been run.",
         )
     if status in (403, 429):
         raise RegistryError(
@@ -52,7 +89,9 @@ def fetch_file(owner: str, repo: str, path: str, ref: str = "main") -> bytes:
     """
     url = f"{GITHUB_RAW_BASE}/{owner}/{repo}/{ref}/{path}"
     try:
-        response = httpx.get(url, headers=_HEADERS, timeout=DEFAULT_TIMEOUT, follow_redirects=True)
+        response = httpx.get(
+            url, headers=_build_headers(), timeout=DEFAULT_TIMEOUT, follow_redirects=True
+        )
     except httpx.TimeoutException as exc:
         raise RegistryError(f"Timeout fetching {owner}/{repo}/{path} at ref {ref}") from exc
     except httpx.HTTPError as exc:
@@ -100,7 +139,7 @@ def list_tags(owner: str, repo: str) -> list[str]:
     url = f"{GITHUB_API_BASE}/repos/{owner}/{repo}/tags"
     try:
         response = httpx.get(
-            url, headers=_API_HEADERS, timeout=DEFAULT_TIMEOUT, follow_redirects=True
+            url, headers=_build_headers(api=True), timeout=DEFAULT_TIMEOUT, follow_redirects=True
         )
     except httpx.TimeoutException as exc:
         raise RegistryError(f"Timeout listing tags for {owner}/{repo}") from exc
@@ -137,7 +176,7 @@ def list_directory(owner: str, repo: str, path: str, ref: str = "main") -> list[
         response = httpx.get(
             url,
             params=params,
-            headers=_API_HEADERS,
+            headers=_build_headers(api=True),
             timeout=DEFAULT_TIMEOUT,
             follow_redirects=True,
         )

From 398017665ec7088db9bff390bafeb49806d94c17 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 08:56:16 -0400
Subject: [PATCH 05/13] fix(registry): use shared github helpers in index
 loader

The index loader was calling httpx.get directly, bypassing the auth
token from gh CLI. Refactored _load_github_index to use
fetch_file_text from github.py, which adds the Bearer token for
private repos.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/registry/index.py   | 24 ++++------
 tests/test_registry/test_index.py | 77 ++++++++++++++-----------------
 2 files changed, 45 insertions(+), 56 deletions(-)

diff --git a/src/conductor/registry/index.py b/src/conductor/registry/index.py
index f9b3a22..2539cae 100644
--- a/src/conductor/registry/index.py
+++ b/src/conductor/registry/index.py
@@ -9,14 +9,12 @@
 import json
 from pathlib import Path
 
-import httpx
 from pydantic import BaseModel
 from ruamel.yaml import YAML, YAMLError
 
 from conductor.registry.config import RegistryEntry, RegistryType
 from conductor.registry.errors import RegistryError
 
-_GITHUB_RAW_BASE = "https://raw.githubusercontent.com"
 _GITHUB_BRANCHES = ("main", "master")
 _INDEX_FILENAMES = ("index.yaml", "index.json")
 
@@ -197,21 +195,19 @@ def _parse_json_file(path: Path) -> RegistryIndex:
 
 
 def _load_github_index(source: str) -> RegistryIndex:
-    """Fetch index from a GitHub repository via raw.githubusercontent.com."""
-    # source is "owner/repo"
+    """Fetch index from a GitHub repository using the shared GitHub helpers."""
+    from conductor.registry.github import fetch_file_text, parse_github_source
+
+    owner, repo = parse_github_source(source)
+
     for filename in _INDEX_FILENAMES:
         for branch in _GITHUB_BRANCHES:
-            url = f"{_GITHUB_RAW_BASE}/{source}/{branch}/{filename}"
             try:
-                resp = httpx.get(url, timeout=30, follow_redirects=True)
-            except httpx.HTTPError as exc:
-                raise RegistryError(
-                    f"Failed to fetch registry index from {url}: {exc}",
-                    suggestion="Check your network connection and the registry source.",
-                ) from exc
-
-            if resp.status_code == 200:
-                return _parse_github_response(resp.text, filename, url)
+                text = fetch_file_text(owner, repo, filename, ref=branch)
+            except RegistryError:
+                continue
+
+            return _parse_github_response(text, filename, f"{source}/{branch}/{filename}")
 
     raise RegistryError(
         f"No index.yaml or index.json found in GitHub repo '{source}' "
diff --git a/tests/test_registry/test_index.py b/tests/test_registry/test_index.py
index 416f344..db235a3 100644
--- a/tests/test_registry/test_index.py
+++ b/tests/test_registry/test_index.py
@@ -167,8 +167,9 @@ def test_empty_workflows(self, tmp_path: Path) -> None:
 class TestLoadGitHubIndex:
     """Tests for loading index from GitHub registries."""
 
-    @patch("conductor.registry.index.httpx.get")
-    def test_fetch_yaml_main(self, mock_get: MagicMock) -> None:
+    @patch("conductor.registry.github.fetch_file_text")
+    @patch("conductor.registry.github.parse_github_source", return_value=("myorg", "myrepo"))
+    def test_fetch_yaml_main(self, _mock_parse: MagicMock, mock_fetch: MagicMock) -> None:
         """Fetches index.yaml from main branch."""
         yaml = YAML(typ="safe")
         from io import StringIO
@@ -177,18 +178,17 @@ def test_fetch_yaml_main(self, mock_get: MagicMock) -> None:
         yaml.dump(_SAMPLE_INDEX, stream)
         yaml_text = stream.getvalue()
 
-        mock_get.return_value = _make_response(200, yaml_text)
+        mock_fetch.return_value = yaml_text
 
         idx = load_index(_github_entry("myorg/myrepo"))
         assert "qa-bot" in idx.workflows
 
-        mock_get.assert_called_once()
-        call_url = mock_get.call_args[0][0]
-        assert "myorg/myrepo/main/index.yaml" in call_url
+        mock_fetch.assert_called_once_with("myorg", "myrepo", "index.yaml", ref="main")
 
-    @patch("conductor.registry.index.httpx.get")
-    def test_fallback_to_master(self, mock_get: MagicMock) -> None:
-        """Falls back to master branch when main returns 404."""
+    @patch("conductor.registry.github.fetch_file_text")
+    @patch("conductor.registry.github.parse_github_source", return_value=("myorg", "myrepo"))
+    def test_fallback_to_master(self, _mock_parse: MagicMock, mock_fetch: MagicMock) -> None:
+        """Falls back to master branch when main raises RegistryError."""
         yaml = YAML(typ="safe")
         from io import StringIO
 
@@ -196,59 +196,52 @@ def test_fallback_to_master(self, mock_get: MagicMock) -> None:
         yaml.dump(_SAMPLE_INDEX, stream)
         yaml_text = stream.getvalue()
 
-        # main returns 404, master returns 200
-        mock_get.side_effect = [
-            _make_response(404),
-            _make_response(200, yaml_text),
+        # main raises error, master succeeds
+        mock_fetch.side_effect = [
+            RegistryError("not found"),
+            yaml_text,
         ]
 
         idx = load_index(_github_entry("myorg/myrepo"))
         assert "qa-bot" in idx.workflows
-        assert mock_get.call_count == 2
+        assert mock_fetch.call_count == 2
 
-        # First call was main, second was master
-        calls = [c[0][0] for c in mock_get.call_args_list]
-        assert "main/index.yaml" in calls[0]
-        assert "master/index.yaml" in calls[1]
-
-    @patch("conductor.registry.index.httpx.get")
-    def test_fallback_to_json(self, mock_get: MagicMock) -> None:
+    @patch("conductor.registry.github.fetch_file_text")
+    @patch("conductor.registry.github.parse_github_source", return_value=("myorg", "myrepo"))
+    def test_fallback_to_json(self, _mock_parse: MagicMock, mock_fetch: MagicMock) -> None:
         """Falls back to index.json when index.yaml not found on any branch."""
         json_text = json.dumps(_SAMPLE_INDEX)
 
-        # yaml on main → 404, yaml on master → 404, json on main → 200
-        mock_get.side_effect = [
-            _make_response(404),
-            _make_response(404),
-            _make_response(200, json_text),
+        # yaml on main → error, yaml on master → error, json on main → success
+        mock_fetch.side_effect = [
+            RegistryError("not found"),
+            RegistryError("not found"),
+            json_text,
         ]
 
         idx = load_index(_github_entry("myorg/myrepo"))
         assert "qa-bot" in idx.workflows
-        assert mock_get.call_count == 3
-
-        calls = [c[0][0] for c in mock_get.call_args_list]
-        assert "index.json" in calls[2]
+        assert mock_fetch.call_count == 3
 
-    @patch("conductor.registry.index.httpx.get")
-    def test_all_404_raises(self, mock_get: MagicMock) -> None:
-        """RegistryError when all fetch attempts return 404."""
-        mock_get.return_value = _make_response(404)
+    @patch("conductor.registry.github.fetch_file_text")
+    @patch("conductor.registry.github.parse_github_source", return_value=("myorg", "myrepo"))
+    def test_all_404_raises(self, _mock_parse: MagicMock, mock_fetch: MagicMock) -> None:
+        """RegistryError when all fetch attempts fail."""
+        mock_fetch.side_effect = RegistryError("not found")
 
         with pytest.raises(RegistryError, match="No index.yaml or index.json"):
             load_index(_github_entry("myorg/myrepo"))
 
         # yaml(main, master) + json(main, master) = 4 attempts
-        assert mock_get.call_count == 4
+        assert mock_fetch.call_count == 4
 
-    @patch("conductor.registry.index.httpx.get")
-    def test_network_error_raises(self, mock_get: MagicMock) -> None:
-        """RegistryError on network failure."""
-        import httpx as _httpx
+    @patch("conductor.registry.github.fetch_file_text")
+    @patch("conductor.registry.github.parse_github_source", return_value=("myorg", "myrepo"))
+    def test_network_error_raises(self, _mock_parse: MagicMock, mock_fetch: MagicMock) -> None:
+        """RegistryError on network failure propagates."""
+        mock_fetch.side_effect = RegistryError("Failed to fetch: connection refused")
 
-        mock_get.side_effect = _httpx.ConnectError("connection refused")
-
-        with pytest.raises(RegistryError, match="Failed to fetch"):
+        with pytest.raises(RegistryError, match="No index.yaml or index.json"):
             load_index(_github_entry("myorg/myrepo"))
 
 

From 0e9bca980e1abd70317a5be031377c6eea831678 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 08:58:35 -0400
Subject: [PATCH 06/13] fix(registry): show command accepts registry name or
 workflow ref

When `conductor registry show <name>` matches a configured registry
name, it displays the registry details and its workflows instead of
trying to parse the name as a workflow reference.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/registry.py | 47 +++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/src/conductor/cli/registry.py b/src/conductor/cli/registry.py
index d73b43a..db48628 100644
--- a/src/conductor/cli/registry.py
+++ b/src/conductor/cli/registry.py
@@ -10,6 +10,7 @@
 
 from conductor.registry.cache import clear_cache, get_cached_workflow_path
 from conductor.registry.config import (
+    RegistryEntry,
     RegistryType,
     add_registry,
     get_registry,
@@ -190,10 +191,24 @@ def update(
 def show(
     ref: Annotated[
         str,
-        typer.Argument(help="Workflow reference (name[@registry][@version])."),
+        typer.Argument(help="Workflow reference (name[@registry][@version]) or registry name."),
     ],
 ) -> None:
-    """Show metadata and cached path for a workflow reference."""
+    """Show metadata and cached path for a workflow reference.
+
+    If the argument matches a configured registry name, shows that registry's
+    workflows instead (equivalent to ``conductor registry list <name>``).
+    """
+    # If the argument is a known registry name, show its workflows instead
+    config = load_config()
+    if ref in config.registries:
+        try:
+            _show_registry(ref, config.registries[ref])
+        except RegistryError as e:
+            console.print(f"[bold red]Error:[/bold red] {e}")
+            raise typer.Exit(code=1) from None
+        return
+
     try:
         resolved = resolve_ref(ref)
         if resolved.kind == "file":
@@ -208,6 +223,10 @@ def show(
         if resolved.workflow not in index.workflows:
             raise RegistryError(
                 f"Workflow '{resolved.workflow}' not found in registry '{resolved.registry_name}'",
+                suggestion=(
+                    f"Run 'conductor registry list {resolved.registry_name}' "
+                    "to see available workflows."
+                ),
             )
 
         info = index.workflows[resolved.workflow]
@@ -228,3 +247,27 @@ def show(
     except RegistryError as e:
         console.print(f"[bold red]Error:[/bold red] {e}")
         raise typer.Exit(code=1) from None
+
+
+def _show_registry(name: str, entry: RegistryEntry) -> None:
+    """Show a registry's details and its workflows."""
+    output_console.print(f"[bold]Registry:[/bold]  {name}")
+    output_console.print(f"[bold]Type:[/bold]      {entry.type.value}")
+    output_console.print(f"[bold]Source:[/bold]    {entry.source}")
+    output_console.print()
+
+    index = load_index(entry)
+    if not index.workflows:
+        output_console.print("No workflows found.")
+        return
+
+    table = Table(title="Workflows")
+    table.add_column("Name", style="cyan")
+    table.add_column("Description")
+    table.add_column("Versions", style="green")
+
+    for wf_name, info in index.workflows.items():
+        versions = ", ".join(info.versions) if info.versions else "-"
+        table.add_row(wf_name, info.description or "-", versions)
+
+    output_console.print(table)

From 0a2c73338d9163fca68745123ea18bf5893581c8 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:05:59 -0400
Subject: [PATCH 07/13] feat(registry): show workflow inputs in registry show
 command

`conductor registry show <workflow>` now fetches the workflow and
displays its input parameters (name, type, required, default,
description) in a table, plus an example run command.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/registry.py | 56 +++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/src/conductor/cli/registry.py b/src/conductor/cli/registry.py
index db48628..f36fc05 100644
--- a/src/conductor/cli/registry.py
+++ b/src/conductor/cli/registry.py
@@ -8,7 +8,7 @@
 from rich.console import Console
 from rich.table import Table
 
-from conductor.registry.cache import clear_cache, get_cached_workflow_path
+from conductor.registry.cache import clear_cache, fetch_workflow, get_cached_workflow_path
 from conductor.registry.config import (
     RegistryEntry,
     RegistryType,
@@ -20,7 +20,7 @@
 )
 from conductor.registry.errors import RegistryError
 from conductor.registry.index import load_index
-from conductor.registry.resolver import resolve_ref
+from conductor.registry.resolver import ResolvedRef, resolve_ref
 
 registry_app = typer.Typer(
     name="registry",
@@ -244,6 +244,9 @@ def show(
         if version:
             cached = get_cached_workflow_path(resolved.registry_name, resolved.workflow, version)
             output_console.print(f"[bold]Cached:[/bold]    {cached or 'not cached'}")
+
+        # Fetch and display workflow inputs
+        _show_workflow_inputs(resolved, version)
     except RegistryError as e:
         console.print(f"[bold red]Error:[/bold red] {e}")
         raise typer.Exit(code=1) from None
@@ -271,3 +274,52 @@ def _show_registry(name: str, entry: RegistryEntry) -> None:
         table.add_row(wf_name, info.description or "-", versions)
 
     output_console.print(table)
+
+
+def _show_workflow_inputs(resolved: ResolvedRef, version: str | None) -> None:
+    """Fetch the workflow and display its input parameters."""
+    assert resolved.registry_entry is not None
+    assert resolved.registry_name is not None
+    assert resolved.workflow is not None
+
+    try:
+        workflow_path = fetch_workflow(
+            registry_name=resolved.registry_name,
+            registry_entry=resolved.registry_entry,
+            workflow_name=resolved.workflow,
+            version=version,
+        )
+    except RegistryError:
+        return
+
+    try:
+        from conductor.config.loader import load_config as load_workflow_config
+
+        config = load_workflow_config(workflow_path)
+    except Exception:
+        return
+
+    inputs = config.workflow.input
+    if not inputs:
+        output_console.print("\n[bold]Inputs:[/bold]    (none)")
+        return
+
+    output_console.print()
+    table = Table(title="Inputs")
+    table.add_column("Name", style="cyan")
+    table.add_column("Type", style="green")
+    table.add_column("Required", justify="center")
+    table.add_column("Default")
+    table.add_column("Description")
+
+    for name, input_def in inputs.items():
+        required = "✓" if input_def.required else ""
+        default = str(input_def.default) if input_def.default is not None else "-"
+        table.add_row(name, input_def.type, required, default, input_def.description or "-")
+
+    output_console.print(table)
+
+    input_args = " ".join(f'--input {name}="..."' for name in inputs)
+    output_console.print(
+        f"\n[dim]Example: conductor run {resolved.workflow} {input_args}[/dim]"
+    )

From 72b0568c7c14315c89beeb09683c28cc74218b9c Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:14:27 -0400
Subject: [PATCH 08/13] feat: add top-level `conductor show` command for
 workflow details
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Split the show UX cleanly:
- `conductor registry show <registry>` — registry info + workflow list
- `conductor show <workflow-ref>` — workflow details, inputs table,
  and example run command

Both registry show and list now hint at `conductor show` for details.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/app.py                 | 100 ++++++++++++++++++++
 src/conductor/cli/registry.py            | 113 ++---------------------
 tests/test_cli/test_registry_commands.py |  20 ++--
 3 files changed, 118 insertions(+), 115 deletions(-)

diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py
index 3ddf6b5..71c2f6c 100644
--- a/src/conductor/cli/app.py
+++ b/src/conductor/cli/app.py
@@ -492,6 +492,106 @@ def validate(
         raise typer.Exit(code=1)
 
 
+@app.command()
+def show(
+    workflow: Annotated[
+        str,
+        typer.Argument(
+            help="Workflow file path or registry reference (name[@registry][@version]).",
+        ),
+    ],
+) -> None:
+    """Show details and inputs for a workflow.
+
+    Accepts a local file path or a registry reference. Displays the workflow
+    name, description, and a table of input parameters.
+
+    \b
+    Examples:
+        conductor show ./my-workflow.yaml
+        conductor show qa-bot
+        conductor show qa-bot@my-registry@1.0.0
+    """
+    from conductor.registry.cache import fetch_workflow as fetch_registry_workflow
+    from conductor.registry.errors import RegistryError
+    from conductor.registry.resolver import resolve_ref
+
+    try:
+        ref = resolve_ref(workflow)
+        if ref.kind == "file":
+            assert ref.path is not None
+            workflow_path = ref.path
+            if not workflow_path.exists():
+                console.print(
+                    f"[bold red]Error:[/bold red] Workflow file not found: {workflow}"
+                )
+                raise typer.Exit(code=1)
+        else:
+            assert ref.registry_name is not None
+            assert ref.registry_entry is not None
+            assert ref.workflow is not None
+            workflow_path = fetch_registry_workflow(
+                registry_name=ref.registry_name,
+                registry_entry=ref.registry_entry,
+                workflow_name=ref.workflow,
+                version=ref.version,
+            )
+    except RegistryError as e:
+        print_error(e)
+        raise typer.Exit(code=1) from None
+
+    try:
+        from conductor.config.loader import load_config as load_workflow_config
+
+        config = load_workflow_config(workflow_path)
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] Failed to parse workflow: {e}")
+        raise typer.Exit(code=1) from None
+
+    wf = config.workflow
+    output_console.print(f"[bold]Name:[/bold]        {wf.name}")
+    if wf.description:
+        output_console.print(f"[bold]Description:[/bold] {wf.description}")
+    output_console.print(f"[bold]Entry point:[/bold] {wf.entry_point}")
+    output_console.print(f"[bold]Source:[/bold]      {workflow_path}")
+
+    if ref.kind == "registry":
+        output_console.print(f"[bold]Registry:[/bold]    {ref.registry_name}")
+        if ref.version:
+            output_console.print(f"[bold]Version:[/bold]     {ref.version}")
+
+    inputs = wf.input
+    if not inputs:
+        output_console.print("\n[dim]This workflow has no inputs.[/dim]")
+    else:
+        from rich.table import Table
+
+        output_console.print()
+        table = Table(title="Inputs")
+        table.add_column("Name", style="cyan")
+        table.add_column("Type", style="green")
+        table.add_column("Required", justify="center")
+        table.add_column("Default")
+        table.add_column("Description")
+
+        for name, input_def in inputs.items():
+            required = "✓" if input_def.required else ""
+            default = str(input_def.default) if input_def.default is not None else "-"
+            table.add_row(
+                name, input_def.type, required, default, input_def.description or "-"
+            )
+
+        output_console.print(table)
+
+    # Show example run command
+    ref_str = workflow if ref.kind == "registry" else str(workflow_path)
+    if inputs:
+        input_args = " ".join(f'--input {name}="..."' for name in inputs)
+        output_console.print(f"\n[dim]conductor run {ref_str} {input_args}[/dim]")
+    else:
+        output_console.print(f"\n[dim]conductor run {ref_str}[/dim]")
+
+
 @app.command()
 def resume(
     workflow: Annotated[
diff --git a/src/conductor/cli/registry.py b/src/conductor/cli/registry.py
index f36fc05..b5e25d9 100644
--- a/src/conductor/cli/registry.py
+++ b/src/conductor/cli/registry.py
@@ -8,7 +8,7 @@
 from rich.console import Console
 from rich.table import Table
 
-from conductor.registry.cache import clear_cache, fetch_workflow, get_cached_workflow_path
+from conductor.registry.cache import clear_cache
 from conductor.registry.config import (
     RegistryEntry,
     RegistryType,
@@ -20,7 +20,6 @@
 )
 from conductor.registry.errors import RegistryError
 from conductor.registry.index import load_index
-from conductor.registry.resolver import ResolvedRef, resolve_ref
 
 registry_app = typer.Typer(
     name="registry",
@@ -91,6 +90,9 @@ def _list_registry_workflows(name: str) -> None:
         table.add_row(wf_name, info.description or "-", versions)
 
     output_console.print(table)
+    output_console.print(
+        "\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]"
+    )
 
 
 @registry_app.command()
@@ -189,64 +191,15 @@ def update(
 
 @registry_app.command()
 def show(
-    ref: Annotated[
+    name: Annotated[
         str,
-        typer.Argument(help="Workflow reference (name[@registry][@version]) or registry name."),
+        typer.Argument(help="Registry name."),
     ],
 ) -> None:
-    """Show metadata and cached path for a workflow reference.
-
-    If the argument matches a configured registry name, shows that registry's
-    workflows instead (equivalent to ``conductor registry list <name>``).
-    """
-    # If the argument is a known registry name, show its workflows instead
-    config = load_config()
-    if ref in config.registries:
-        try:
-            _show_registry(ref, config.registries[ref])
-        except RegistryError as e:
-            console.print(f"[bold red]Error:[/bold red] {e}")
-            raise typer.Exit(code=1) from None
-        return
-
+    """Show details and workflows for a configured registry."""
     try:
-        resolved = resolve_ref(ref)
-        if resolved.kind == "file":
-            output_console.print(f"Local file: {resolved.path}")
-            return
-
-        assert resolved.registry_entry is not None
-        assert resolved.registry_name is not None
-        assert resolved.workflow is not None
-
-        index = load_index(resolved.registry_entry)
-        if resolved.workflow not in index.workflows:
-            raise RegistryError(
-                f"Workflow '{resolved.workflow}' not found in registry '{resolved.registry_name}'",
-                suggestion=(
-                    f"Run 'conductor registry list {resolved.registry_name}' "
-                    "to see available workflows."
-                ),
-            )
-
-        info = index.workflows[resolved.workflow]
-        version = resolved.version or (info.versions[-1] if info.versions else None)
-
-        output_console.print(f"[bold]Workflow:[/bold]  {resolved.workflow}")
-        output_console.print(f"[bold]Registry:[/bold]  {resolved.registry_name}")
-        output_console.print(f"[bold]Description:[/bold] {info.description or '-'}")
-        output_console.print(f"[bold]Path:[/bold]      {info.path}")
-        output_console.print(
-            f"[bold]Versions:[/bold]  {', '.join(info.versions) if info.versions else '-'}"
-        )
-        output_console.print(f"[bold]Version:[/bold]   {version or 'latest'}")
-
-        if version:
-            cached = get_cached_workflow_path(resolved.registry_name, resolved.workflow, version)
-            output_console.print(f"[bold]Cached:[/bold]    {cached or 'not cached'}")
-
-        # Fetch and display workflow inputs
-        _show_workflow_inputs(resolved, version)
+        entry = get_registry(name)
+        _show_registry(name, entry)
     except RegistryError as e:
         console.print(f"[bold red]Error:[/bold red] {e}")
         raise typer.Exit(code=1) from None
@@ -274,52 +227,6 @@ def _show_registry(name: str, entry: RegistryEntry) -> None:
         table.add_row(wf_name, info.description or "-", versions)
 
     output_console.print(table)
-
-
-def _show_workflow_inputs(resolved: ResolvedRef, version: str | None) -> None:
-    """Fetch the workflow and display its input parameters."""
-    assert resolved.registry_entry is not None
-    assert resolved.registry_name is not None
-    assert resolved.workflow is not None
-
-    try:
-        workflow_path = fetch_workflow(
-            registry_name=resolved.registry_name,
-            registry_entry=resolved.registry_entry,
-            workflow_name=resolved.workflow,
-            version=version,
-        )
-    except RegistryError:
-        return
-
-    try:
-        from conductor.config.loader import load_config as load_workflow_config
-
-        config = load_workflow_config(workflow_path)
-    except Exception:
-        return
-
-    inputs = config.workflow.input
-    if not inputs:
-        output_console.print("\n[bold]Inputs:[/bold]    (none)")
-        return
-
-    output_console.print()
-    table = Table(title="Inputs")
-    table.add_column("Name", style="cyan")
-    table.add_column("Type", style="green")
-    table.add_column("Required", justify="center")
-    table.add_column("Default")
-    table.add_column("Description")
-
-    for name, input_def in inputs.items():
-        required = "✓" if input_def.required else ""
-        default = str(input_def.default) if input_def.default is not None else "-"
-        table.add_row(name, input_def.type, required, default, input_def.description or "-")
-
-    output_console.print(table)
-
-    input_args = " ".join(f'--input {name}="..."' for name in inputs)
     output_console.print(
-        f"\n[dim]Example: conductor run {resolved.workflow} {input_args}[/dim]"
+        "\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]"
     )
diff --git a/tests/test_cli/test_registry_commands.py b/tests/test_cli/test_registry_commands.py
index 10c021c..712cf67 100644
--- a/tests/test_cli/test_registry_commands.py
+++ b/tests/test_cli/test_registry_commands.py
@@ -175,9 +175,9 @@ def test_set_default_nonexistent(self) -> None:
 
 
 class TestShow:
-    """Showing workflow metadata."""
+    """Showing registry details."""
 
-    def test_show_workflow(self) -> None:
+    def test_show_registry(self) -> None:
         runner.invoke(app, ["registry", "add", "team", "acme/workflows", "--default"])
 
         mock_index = RegistryIndex(
@@ -189,21 +189,17 @@ def test_show_workflow(self) -> None:
         )
 
         with patch("conductor.cli.registry.load_index", return_value=mock_index):
-            result = runner.invoke(app, ["registry", "show", "qa-bot"])
+            result = runner.invoke(app, ["registry", "show", "team"])
 
         assert result.exit_code == 0
+        assert "team" in result.output
+        assert "acme/workflows" in result.output
         assert "qa-bot" in result.output
         assert "QA helper" in result.output
-        assert "qa/bot.yaml" in result.output
-        assert "1.0" in result.output
-
-    def test_show_unknown_workflow(self) -> None:
-        runner.invoke(app, ["registry", "add", "team", "acme/workflows", "--default"])
-
-        mock_index = RegistryIndex(workflows={})
+        assert "conductor show" in result.output
 
-        with patch("conductor.cli.registry.load_index", return_value=mock_index):
-            result = runner.invoke(app, ["registry", "show", "missing"])
+    def test_show_unknown_registry(self) -> None:
+        result = runner.invoke(app, ["registry", "show", "missing"])
 
         assert result.exit_code == 1
         assert "not found" in result.output

From 67b9d150276b8b68a2830386e8e88df189303435 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:22:38 -0400
Subject: [PATCH 09/13] fix(registry): path registries read directly from
 source

Local path registries now return the source file path directly instead
of copying to cache. This means edits to workflow files are reflected
immediately without needing `conductor registry update`. Versioning
is skipped for path registries since there's no version control.

GitHub registries still use the cache as before.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/registry/cache.py         | 74 +++++++++----------------
 tests/test_registry/test_cache.py       | 52 ++++++++---------
 tests/test_registry/test_integration.py | 12 ++--
 3 files changed, 52 insertions(+), 86 deletions(-)

diff --git a/src/conductor/registry/cache.py b/src/conductor/registry/cache.py
index a4bbf2b..5803a36 100644
--- a/src/conductor/registry/cache.py
+++ b/src/conductor/registry/cache.py
@@ -1,10 +1,13 @@
 """Local workflow cache management.
 
 Manages the on-disk cache at ``~/.conductor/cache/registries/`` (or under
-``$CONDUCTOR_HOME``).  Workflows fetched from remote registries are stored
+``$CONDUCTOR_HOME``).  Workflows fetched from GitHub registries are stored
 here so that subsequent runs can resolve to a stable filesystem path — a
 requirement for ``!file`` tag resolution and checkpoint identity.
 
+Path registries are read directly from the source directory (no caching)
+so that local edits are reflected immediately.
+
 Cache layout::
 
     <base>/cache/registries/<registry>/<workflow>/<version>/
@@ -117,11 +120,7 @@ def fetch_workflow(
     # 1. Load the index
     index = load_index(registry_entry)
 
-    # 2. Resolve version
-    if version is None:
-        version = resolve_latest(index, workflow_name)
-
-    # 3. Look up workflow metadata from the index
+    # 2. Look up workflow metadata from the index
     if workflow_name not in index.workflows:
         raise RegistryError(
             f"Workflow '{workflow_name}' not found in registry '{registry_name}'",
@@ -129,21 +128,33 @@ def fetch_workflow(
         )
     workflow_info = index.workflows[workflow_name]
 
-    # 4. Check cache (explicit versions are immutable)
+    # 3. For path registries, read directly from source (no caching, no versioning)
+    if registry_entry.type == RegistryType.path:
+        source_path = Path(registry_entry.source) / workflow_info.path
+        if not source_path.exists():
+            raise RegistryError(
+                f"Workflow file not found at '{source_path}'",
+                suggestion="Verify the 'path' field in the registry's index.yaml.",
+                file_path=str(source_path),
+            )
+        return source_path
+
+    # 4. For GitHub registries, resolve version
+    if version is None:
+        version = resolve_latest(index, workflow_name)
+
+    # 5. Check cache (explicit versions are immutable)
     cached = get_cached_workflow_path(registry_name, workflow_name, version)
     if cached is not None:
         return cached
 
-    # 5. Prepare cache directory
+    # 6. Prepare cache directory
     version_dir = get_cache_base() / registry_name / workflow_name / version
     version_dir.mkdir(parents=True, exist_ok=True)
 
-    # 6. Fetch based on registry type
+    # 7. Fetch from GitHub
     try:
-        if registry_entry.type == RegistryType.github:
-            _fetch_github(registry_entry, workflow_info.path, version, version_dir)
-        else:
-            _fetch_path(registry_entry, workflow_info.path, version_dir)
+        _fetch_github(registry_entry, workflow_info.path, version, version_dir)
     except RegistryError:
         raise
     except Exception as exc:
@@ -152,7 +163,7 @@ def fetch_workflow(
             suggestion="Check your network connection and registry configuration.",
         ) from exc
 
-    # 7. Return the cached workflow path
+    # 8. Return the cached workflow path
     workflow_filename = Path(workflow_info.path).name
     result = version_dir / workflow_filename
     if not result.exists():
@@ -210,41 +221,6 @@ def _fetch_github(
             pass
 
 
-# ---------------------------------------------------------------------------
-# Path (local) fetch
-# ---------------------------------------------------------------------------
-
-
-def _fetch_path(
-    registry_entry: RegistryEntry,
-    workflow_path: str,
-    dest_dir: Path,
-) -> None:
-    """Copy a workflow and its sibling files from a local path registry.
-
-    Args:
-        registry_entry: Registry entry with ``source`` as a filesystem path.
-        workflow_path: Relative path to the workflow YAML within the source.
-        dest_dir: Local directory to write files into.
-    """
-    source_root = Path(registry_entry.source)
-    source_file = source_root / workflow_path
-
-    if not source_file.exists():
-        raise RegistryError(
-            f"Workflow file not found at '{source_file}'",
-            suggestion="Verify the 'path' field in the registry's index.yaml.",
-            file_path=str(source_file),
-        )
-
-    source_dir = source_file.parent
-
-    # Copy all files in the workflow's directory
-    for item in source_dir.iterdir():
-        if item.is_file():
-            shutil.copy2(item, dest_dir / item.name)
-
-
 # ---------------------------------------------------------------------------
 # Cache management
 # ---------------------------------------------------------------------------
diff --git a/tests/test_registry/test_cache.py b/tests/test_registry/test_cache.py
index 62be982..bca491c 100644
--- a/tests/test_registry/test_cache.py
+++ b/tests/test_registry/test_cache.py
@@ -149,10 +149,11 @@ def _make_index(self) -> _FakeIndex:
         )
 
     @patch("conductor.registry.cache.load_index")
-    def test_fetches_and_caches(
+    def test_returns_source_path_directly(
         self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        home = _setup_conductor_home(tmp_path, monkeypatch)
+        """Path registries return the source file directly (no caching)."""
+        _setup_conductor_home(tmp_path, monkeypatch)
         registry_dir = _create_path_registry(tmp_path)
         mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
 
@@ -161,53 +162,45 @@ def test_fetches_and_caches(
 
         assert result.exists()
         assert result.name == "qa-bot.yaml"
-        assert "local" in str(result)
-        assert "1.0.0" in str(result)
-
-        # Sibling file should be cached too
-        sibling = result.parent / "prompt.txt"
-        assert sibling.exists()
-
-        # Verify cache directory is under CONDUCTOR_HOME
-        assert str(result).startswith(str(home))
+        # Should point to the source directory, not the cache
+        assert str(result).startswith(str(registry_dir))
 
     @patch("conductor.registry.cache.load_index")
-    def test_second_fetch_returns_cached(
+    def test_version_is_ignored(
         self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Path registries ignore the version — same file regardless."""
         _setup_conductor_home(tmp_path, monkeypatch)
         registry_dir = _create_path_registry(tmp_path)
         mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
 
         entry = RegistryEntry(type=RegistryType.path, source=str(registry_dir))
 
-        first = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
-        second = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+        v1 = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+        v2 = fetch_workflow("local", entry, "qa-bot", version="2.0.0")
+        latest = fetch_workflow("local", entry, "qa-bot", version=None)
 
-        assert first == second
-        # load_index is still called (to check workflow exists + resolve version),
-        # but the file system copy should only happen once
-        assert mock_load_index.call_count == 2  # type: ignore[union-attr]
+        # All return the same source file
+        assert v1 == v2 == latest
 
-    @patch("conductor.registry.cache.resolve_latest", return_value="2.0.0")
     @patch("conductor.registry.cache.load_index")
-    def test_resolves_latest(
-        self,
-        mock_load_index: object,
-        mock_resolve_latest: object,
-        tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
+    def test_edits_reflected_immediately(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
+        """Changes to the source file are visible without cache refresh."""
         _setup_conductor_home(tmp_path, monkeypatch)
         registry_dir = _create_path_registry(tmp_path)
         mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
 
         entry = RegistryEntry(type=RegistryType.path, source=str(registry_dir))
-        result = fetch_workflow("local", entry, "qa-bot", version=None)
+        result = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
 
-        mock_resolve_latest.assert_called_once()  # type: ignore[union-attr]
-        assert result.exists()
-        assert "2.0.0" in str(result)
+        original = result.read_text()
+        result.write_text(original + "\n# edited")
+
+        # Re-fetch returns the same path with the edit visible
+        result2 = fetch_workflow("local", entry, "qa-bot", version="1.0.0")
+        assert "# edited" in result2.read_text()
 
     @patch("conductor.registry.cache.load_index")
     def test_missing_workflow_raises(
@@ -227,7 +220,6 @@ def test_missing_source_file_raises(
         _setup_conductor_home(tmp_path, monkeypatch)
         mock_load_index.return_value = self._make_index()  # type: ignore[union-attr]
 
-        # Source dir exists but the workflow file doesn't
         empty_registry = tmp_path / "empty-registry"
         empty_registry.mkdir()
         entry = RegistryEntry(type=RegistryType.path, source=str(empty_registry))
diff --git a/tests/test_registry/test_integration.py b/tests/test_registry/test_integration.py
index 98029e7..b0e81f6 100644
--- a/tests/test_registry/test_integration.py
+++ b/tests/test_registry/test_integration.py
@@ -210,8 +210,8 @@ def test_resolves_latest_version(self, tmp_path: Path, monkeypatch: pytest.Monke
         cached = fetch_workflow("ver-reg", ref.registry_entry, "multi-ver")
         assert cached.exists()
 
-        # The cache directory should be under the "2.0.0" version folder
-        assert "2.0.0" in str(cached)
+        # Path registries return source path directly (version is ignored)
+        assert str(cached).startswith(str(reg_dir))
 
 
 # ---------------------------------------------------------------------------
@@ -246,15 +246,13 @@ def test_second_fetch_returns_cached(
         # First fetch
         path1 = fetch_workflow("cache-reg", ref.registry_entry, "cached-wf", version="1.0.0")
 
-        # Second fetch — should return the same cached path
+        # Second fetch — should return the same source path
         path2 = fetch_workflow("cache-reg", ref.registry_entry, "cached-wf", version="1.0.0")
 
         assert path1 == path2
         assert path1.exists()
-
-        # Also verify via the direct cache lookup API
-        cached = get_cached_workflow_path("cache-reg", "cached-wf", "1.0.0")
-        assert cached == path1
+        # Path registries don't use cache — returns source directly
+        assert str(path1).startswith(str(reg_dir))
 
 
 # ---------------------------------------------------------------------------

From bde7a1ce0e3dc5c543535988afb80739fd532ff1 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:24:12 -0400
Subject: [PATCH 10/13] feat: conductor show displays inputs, agents, and
 outputs

The show command now displays three tables:
- Inputs: name, type, required, default, description
- Agents: name, type, description, routes (incl. parallel/for-each)
- Outputs: field name and template expression

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/app.py | 51 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 5 deletions(-)

diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py
index 71c2f6c..54c12b8 100644
--- a/src/conductor/cli/app.py
+++ b/src/conductor/cli/app.py
@@ -560,12 +560,11 @@ def show(
         if ref.version:
             output_console.print(f"[bold]Version:[/bold]     {ref.version}")
 
-    inputs = wf.input
-    if not inputs:
-        output_console.print("\n[dim]This workflow has no inputs.[/dim]")
-    else:
-        from rich.table import Table
+    from rich.table import Table
 
+    # --- Inputs ---
+    inputs = wf.input
+    if inputs:
         output_console.print()
         table = Table(title="Inputs")
         table.add_column("Name", style="cyan")
@@ -583,6 +582,48 @@ def show(
 
         output_console.print(table)
 
+    # --- Agents ---
+    output_console.print()
+    agent_table = Table(title="Agents")
+    agent_table.add_column("Name", style="cyan")
+    agent_table.add_column("Type", style="green")
+    agent_table.add_column("Description")
+    agent_table.add_column("Routes")
+
+    for agent in config.agents:
+        agent_type = agent.type or "agent"
+        routes = ", ".join(
+            r.to + (f" (when {r.when})" if r.when else "") for r in agent.routes
+        )
+        agent_table.add_row(
+            agent.name, agent_type, agent.description or "-", routes or "-"
+        )
+
+    # Include parallel groups
+    for pg in config.parallel:
+        members = ", ".join(pg.agents)
+        agent_table.add_row(pg.name, "parallel", members, "-")
+
+    # Include for-each groups
+    for fe in config.for_each:
+        agent_table.add_row(fe.name, "for_each", fe.source or "-", "-")
+
+    output_console.print(agent_table)
+
+    # --- Outputs ---
+    if config.output:
+        output_console.print()
+        out_table = Table(title="Outputs")
+        out_table.add_column("Field", style="cyan")
+        out_table.add_column("Template")
+
+        for field, template in config.output.items():
+            # Truncate long templates
+            display = template if len(template) <= 60 else template[:57] + "..."
+            out_table.add_row(field, display)
+
+        output_console.print(out_table)
+
     # Show example run command
     ref_str = workflow if ref.kind == "registry" else str(workflow_path)
     if inputs:

From 16696c05991c66a7c4cde6d8cea8821a6ae187b5 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:40:38 -0400
Subject: [PATCH 11/13] fix: bump github-copilot-sdk minimum to 0.2.2

v0.2.0 is missing copilot.session.PermissionHandler, causing the SDK
to be detected as unavailable. Pin to >=0.2.2 which has the required
exports.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 pyproject.toml | 2 +-
 uv.lock        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 7d028b4..63e1216 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -37,7 +37,7 @@ dependencies = [
     "ruamel.yaml>=0.18.0",
     "jinja2>=3.1.0",
     "simpleeval>=1.0.0",
-    "github-copilot-sdk>=0.2.0",
+    "github-copilot-sdk>=0.2.2",
     "anthropic>=0.77.0,<1.0.0",
     "mcp>=1.0.0",
     "fastapi>=0.115.0",
diff --git a/uv.lock b/uv.lock
index d74e9be..ac918e3 100644
--- a/uv.lock
+++ b/uv.lock
@@ -181,7 +181,7 @@ dev = [
 requires-dist = [
     { name = "anthropic", specifier = ">=0.77.0,<1.0.0" },
     { name = "fastapi", specifier = ">=0.115.0" },
-    { name = "github-copilot-sdk", specifier = ">=0.2.0" },
+    { name = "github-copilot-sdk", specifier = ">=0.2.2" },
     { name = "httpx", specifier = ">=0.27.0" },
     { name = "jinja2", specifier = ">=3.1.0" },
     { name = "mcp", specifier = ">=1.0.0" },

From 145e2f48b389652c8d0aa55698ce69d85de754de Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 09:59:39 -0400
Subject: [PATCH 12/13] fix: remove unused import in integration tests

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 tests/test_registry/test_integration.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/test_registry/test_integration.py b/tests/test_registry/test_integration.py
index b0e81f6..6a3af50 100644
--- a/tests/test_registry/test_integration.py
+++ b/tests/test_registry/test_integration.py
@@ -12,7 +12,7 @@
 from typer.testing import CliRunner
 
 from conductor.cli.app import app
-from conductor.registry.cache import fetch_workflow, get_cached_workflow_path
+from conductor.registry.cache import fetch_workflow
 from conductor.registry.config import (
     RegistryType,
     add_registry,

From 8355fc3106957721154a1924a39f400c9e374d61 Mon Sep 17 00:00:00 2001
From: Jason Robert <jasont.robert@gmail.com>
Date: Mon, 20 Apr 2026 11:31:09 -0400
Subject: [PATCH 13/13] style: fix ruff formatting in app.py and registry.py

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/conductor/cli/app.py      | 16 ++++------------
 src/conductor/cli/registry.py |  8 ++------
 2 files changed, 6 insertions(+), 18 deletions(-)

diff --git a/src/conductor/cli/app.py b/src/conductor/cli/app.py
index 54c12b8..31c2d23 100644
--- a/src/conductor/cli/app.py
+++ b/src/conductor/cli/app.py
@@ -522,9 +522,7 @@ def show(
             assert ref.path is not None
             workflow_path = ref.path
             if not workflow_path.exists():
-                console.print(
-                    f"[bold red]Error:[/bold red] Workflow file not found: {workflow}"
-                )
+                console.print(f"[bold red]Error:[/bold red] Workflow file not found: {workflow}")
                 raise typer.Exit(code=1)
         else:
             assert ref.registry_name is not None
@@ -576,9 +574,7 @@ def show(
         for name, input_def in inputs.items():
             required = "✓" if input_def.required else ""
             default = str(input_def.default) if input_def.default is not None else "-"
-            table.add_row(
-                name, input_def.type, required, default, input_def.description or "-"
-            )
+            table.add_row(name, input_def.type, required, default, input_def.description or "-")
 
         output_console.print(table)
 
@@ -592,12 +588,8 @@ def show(
 
     for agent in config.agents:
         agent_type = agent.type or "agent"
-        routes = ", ".join(
-            r.to + (f" (when {r.when})" if r.when else "") for r in agent.routes
-        )
-        agent_table.add_row(
-            agent.name, agent_type, agent.description or "-", routes or "-"
-        )
+        routes = ", ".join(r.to + (f" (when {r.when})" if r.when else "") for r in agent.routes)
+        agent_table.add_row(agent.name, agent_type, agent.description or "-", routes or "-")
 
     # Include parallel groups
     for pg in config.parallel:
diff --git a/src/conductor/cli/registry.py b/src/conductor/cli/registry.py
index b5e25d9..d95bbd5 100644
--- a/src/conductor/cli/registry.py
+++ b/src/conductor/cli/registry.py
@@ -90,9 +90,7 @@ def _list_registry_workflows(name: str) -> None:
         table.add_row(wf_name, info.description or "-", versions)
 
     output_console.print(table)
-    output_console.print(
-        "\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]"
-    )
+    output_console.print("\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]")
 
 
 @registry_app.command()
@@ -227,6 +225,4 @@ def _show_registry(name: str, entry: RegistryEntry) -> None:
         table.add_row(wf_name, info.description or "-", versions)
 
     output_console.print(table)
-    output_console.print(
-        "\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]"
-    )
+    output_console.print("\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]")