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..63e1216 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -37,12 +37,13 @@ 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",
     "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..31c2d23 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,29 @@ 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":
+            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,
+                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 +356,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 +381,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 +391,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 +413,7 @@ def run(
         # Run the workflow
         result = asyncio.run(
             run_workflow_async(
-                workflow,
+                workflow_path,
                 inputs,
                 provider,
                 skip_gates,
@@ -413,14 +436,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 +454,186 @@ 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":
+            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,
+                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[
+def show(
+    workflow: Annotated[
         str,
         typer.Argument(
-            help="Name for the new workflow.",
+            help="Workflow file path or registry reference (name[@registry][@version]).",
         ),
     ],
-    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.
+    """Show details and inputs for a workflow.
 
-    Creates a new workflow YAML file based on the specified template.
-    Use 'conductor templates' to see available templates.
+    Accepts a local file path or a registry reference. Displays the workflow
+    name, description, and a table of input parameters.
 
     \b
     Examples:
-        conductor init my-workflow
-        conductor init my-workflow --template loop
-        conductor init my-workflow -t human-gate -o ./workflows/my-workflow.yaml
+        conductor show ./my-workflow.yaml
+        conductor show qa-bot
+        conductor show qa-bot@my-registry@1.0.0
     """
-    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)
+    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:
-        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}")
+        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
 
-@app.command()
-def templates() -> None:
-    """List available workflow templates.
+        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
 
-    Shows all templates that can be used with 'conductor init'.
+    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}")
 
-    \b
-    Examples:
-        conductor templates
-    """
-    from conductor.cli.init import display_templates
+    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}")
 
-    display_templates(output_console)
+    from rich.table import Table
+
+    # --- Inputs ---
+    inputs = wf.input
+    if inputs:
+        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)
+
+    # --- 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:
+        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[
-        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 +703,36 @@ 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":
+                assert ref.path is not None
+                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:
+                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,
+                    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 +748,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..d95bbd5
--- /dev/null
+++ b/src/conductor/cli/registry.py
@@ -0,0 +1,228 @@
+"""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
+from conductor.registry.config import (
+    RegistryEntry,
+    RegistryType,
+    add_registry,
+    get_registry,
+    load_config,
+    remove_registry,
+    save_config,
+)
+from conductor.registry.errors import RegistryError
+from conductor.registry.index import load_index
+
+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)
+    output_console.print("\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]")
+
+
+@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(
+    name: Annotated[
+        str,
+        typer.Argument(help="Registry name."),
+    ],
+) -> None:
+    """Show details and workflows for a configured registry."""
+    try:
+        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
+
+
+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)
+    output_console.print("\n[dim]Use 'conductor show <workflow>' to see inputs and details.[/dim]")
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..5803a36
--- /dev/null
+++ b/src/conductor/registry/cache.py
@@ -0,0 +1,246 @@
+"""Local workflow cache management.
+
+Manages the on-disk cache at ``~/.conductor/cache/registries/`` (or under
+``$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>/
+"""
+
+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. 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]
+
+    # 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
+
+    # 6. Prepare cache directory
+    version_dir = get_cache_base() / registry_name / workflow_name / version
+    version_dir.mkdir(parents=True, exist_ok=True)
+
+    # 7. Fetch from GitHub
+    try:
+        _fetch_github(registry_entry, workflow_info.path, version, 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
+
+    # 8. 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
+
+
+# ---------------------------------------------------------------------------
+# 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..16c65e6
--- /dev/null
+++ b/src/conductor/registry/config.py
@@ -0,0 +1,259 @@
+"""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.
+
+    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.
+        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 or config.default is None:
+        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..9c56237
--- /dev/null
+++ b/src/conductor/registry/github.py
@@ -0,0 +1,215 @@
+"""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
+
+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 _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:
+        return
+    status = response.status_code
+    if status == 404:
+        raise RegistryError(
+            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(
+            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=_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:
+        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=_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
+    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=_build_headers(api=True),
+            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..2539cae
--- /dev/null
+++ b/src/conductor/registry/index.py
@@ -0,0 +1,244 @@
+"""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
+
+from pydantic import BaseModel
+from ruamel.yaml import YAML, YAMLError
+
+from conductor.registry.config import RegistryEntry, RegistryType
+from conductor.registry.errors import RegistryError
+
+_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 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:
+            try:
+                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}' "
+        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..712cf67
--- /dev/null
+++ b/tests/test_cli/test_registry_commands.py
@@ -0,0 +1,254 @@
+"""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 registry details."""
+
+    def test_show_registry(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", "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 "conductor show" in result.output
+
+    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
+
+
+# ---------------------------------------------------------------------------
+# 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..bca491c
--- /dev/null
+++ b/tests/test_registry/test_cache.py
@@ -0,0 +1,354 @@
+"""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_returns_source_path_directly(
+        self, mock_load_index: object, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """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]
+
+        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"
+        # Should point to the source directory, not the cache
+        assert str(result).startswith(str(registry_dir))
+
+    @patch("conductor.registry.cache.load_index")
+    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))
+
+        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)
+
+        # All return the same source file
+        assert v1 == v2 == latest
+
+    @patch("conductor.registry.cache.load_index")
+    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="1.0.0")
+
+        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(
+        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]
+
+        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..db235a3
--- /dev/null
+++ b/tests/test_registry/test_index.py
@@ -0,0 +1,321 @@
+"""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.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
+
+        stream = StringIO()
+        yaml.dump(_SAMPLE_INDEX, stream)
+        yaml_text = stream.getvalue()
+
+        mock_fetch.return_value = yaml_text
+
+        idx = load_index(_github_entry("myorg/myrepo"))
+        assert "qa-bot" in idx.workflows
+
+        mock_fetch.assert_called_once_with("myorg", "myrepo", "index.yaml", ref="main")
+
+    @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
+
+        stream = StringIO()
+        yaml.dump(_SAMPLE_INDEX, stream)
+        yaml_text = stream.getvalue()
+
+        # 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_fetch.call_count == 2
+
+    @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 → 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_fetch.call_count == 3
+
+    @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_fetch.call_count == 4
+
+    @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")
+
+        with pytest.raises(RegistryError, match="No index.yaml or index.json"):
+            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..6a3af50
--- /dev/null
+++ b/tests/test_registry/test_integration.py
@@ -0,0 +1,467 @@
+"""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
+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()
+
+        # Path registries return source path directly (version is ignored)
+        assert str(cached).startswith(str(reg_dir))
+
+
+# ---------------------------------------------------------------------------
+# 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 source path
+        path2 = fetch_workflow("cache-reg", ref.registry_entry, "cached-wf", version="1.0.0")
+
+        assert path1 == path2
+        assert path1.exists()
+        # Path registries don't use cache — returns source directly
+        assert str(path1).startswith(str(reg_dir))
+
+
+# ---------------------------------------------------------------------------
+# 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..ac918e3 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" },
@@ -180,7 +181,8 @@ 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" },
     { name = "pydantic", specifier = ">=2.0.0" },