From 6561ccca7e5f25ebbf1c0871e998f41e6c2ad3ae Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:26:12 -0400
Subject: [PATCH 1/6] feat(manifest): make comments and order durable in the
 manifest source

Adds an outline pass over the authored manifest text: components,
groups, and files/repos/manifests members are walked in authored
order with source line spans, block/end-of-line comments, and
commented-out list items recognized as disabled members. Disabled
members produce no payload and are never resolved (they were already
invisible to the YAML parser); what's new is that they're now
surfaced in index.json instead of silently discarded.

Verbatim source preservation (58e0ee3) is extended to keep disabled
members and their comments in hydrated `manifest.yaml` copies rather
than stripping them, since they're deliberate authored curation.
---
 src/contextualize/manifest/hydrate.py |   2 +
 src/contextualize/manifest/source.py  | 488 +++++++++++++++++++++++---
 tests/test_hydrate_plugins.py         |  67 ++++
 tests/test_manifest_source.py         |  27 +-
 4 files changed, 539 insertions(+), 45 deletions(-)
diff --git a/src/contextualize/manifest/hydrate.py b/src/contextualize/manifest/hydrate.py
index dd3f06c..a5687cd 100644
--- a/src/contextualize/manifest/hydrate.py
+++ b/src/contextualize/manifest/hydrate.py
@@ -1006,6 +1006,8 @@ def build_hydration_plan_data(
         )
         if manifest_source is not None:
             index_data["manifest_source"] = manifest_source
+        if manifest_format is not None and manifest_format.outline:
+            index_data["outline"] = manifest_format.outline
         index_text = _dump_index(index_data)
         files_to_write.append((context_dir / "index.json", index_text))
 
diff --git a/src/contextualize/manifest/source.py b/src/contextualize/manifest/source.py
index 6e39400..4f8a3dc 100644
--- a/src/contextualize/manifest/source.py
+++ b/src/contextualize/manifest/source.py
@@ -8,7 +8,7 @@
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 import yaml
 
@@ -25,6 +25,7 @@ class ManifestFormat:
     line: int
     source_path: str | None
     group_slices: dict[tuple[str, ...], ManifestSlice]
+    outline: list[dict[str, Any]]
 
 
 @dataclass(frozen=True)
@@ -39,6 +40,11 @@ class ManifestSource:
     r"(?ms)^```(?P<label>[A-Za-z0-9_-]*)[^\n]*\n(?P<body>.*?)^```[ \t]*$"
 )
 
+_MEMBER_KEYS = ("files", "repos", "manifests")
+_COMPONENT_KEY_NAMES = ("name", "group", "set")
+_DASH_ITEM_RE = re.compile(r"^(?P<indent> *)-(?P<rest>.*)$")
+_DISABLED_ITEM_RE = re.compile(r"^(?P<indent> *)#[ \t]*-[ \t]+(?P<rest>.*)$")
+
 
 def load_manifest_source(path: str | os.PathLike[str]) -> ManifestSource:
     source_path = Path(path).expanduser()
@@ -178,49 +184,29 @@ def _build_manifest_format(
     source_path: str | None,
     line: int,
 ) -> ManifestFormat:
-    filtered, source_lines = _strip_commented_list_items(body, line)
+    lines = body.splitlines(keepends=True)
     return ManifestFormat(
-        body=filtered,
+        body=body,
         line=line,
         source_path=source_path,
-        group_slices=_extract_group_slices(filtered, source_lines),
+        group_slices=_extract_group_slices(lines, line),
+        outline=_build_outline(lines, line),
     )
 
 
-def _strip_commented_list_items(text: str, start_line: int) -> tuple[str, list[int]]:
-    lines = text.splitlines(keepends=True)
-    kept: list[str] = []
-    source_lines: list[int] = []
-    skip_indent: int | None = None
-    for offset, line in enumerate(lines):
-        stripped = line.strip()
-        indent = len(line) - len(line.lstrip(" \t"))
-        if skip_indent is not None:
-            if not stripped:
-                skip_indent = None
-            elif stripped.startswith("#") and indent >= skip_indent:
-                continue
-            else:
-                skip_indent = None
-        if re.match(r"^[ \t]*#[ \t]*-[ \t]+", line):
-            skip_indent = indent
-            continue
-        kept.append(line)
-        source_lines.append(start_line + offset)
-    return "".join(kept), source_lines
+# --- group manifest slicing (hydrated `.context/<name>/**/manifest.yaml` copies) ---
 
 
 def _extract_group_slices(
-    text: str,
-    source_lines: list[int],
+    lines: list[str],
+    start_line: int,
 ) -> dict[tuple[str, ...], ManifestSlice]:
-    lines = text.splitlines(keepends=True)
     components_range = _find_components_range(lines, 0, len(lines), max_indent=0)
     if components_range is None:
         return {}
     start, end = components_range
     group_slices: dict[tuple[str, ...], ManifestSlice] = {}
-    _collect_group_slices(lines, start, end, (), group_slices, source_lines)
+    _collect_group_slices(lines, start, end, (), group_slices, start_line)
     return group_slices
 
 
@@ -248,7 +234,7 @@ def _collect_group_slices(
     end: int,
     parent_path: tuple[str, ...],
     group_slices: dict[tuple[str, ...], ManifestSlice],
-    source_lines: list[int],
+    start_line: int,
 ) -> None:
     index = start
     while index < end:
@@ -270,7 +256,7 @@ def _collect_group_slices(
         group_path = parent_path + (group_name,)
         group_slices[group_path] = ManifestSlice(
             body=_build_group_manifest_slice(lines[index:item_end], item_indent),
-            line=source_lines[index],
+            line=start_line + index,
         )
         child_range = _find_components_range(
             lines,
@@ -286,23 +272,13 @@ def _collect_group_slices(
                 child_end,
                 group_path,
                 group_slices,
-                source_lines,
+                start_line,
             )
         index = item_end
 
 
 def _parse_group_name(raw: str) -> str | None:
-    raw = raw.strip()
-    if not raw:
-        return None
-    try:
-        value = yaml.safe_load(raw)
-    except Exception:
-        value = raw
-    if not isinstance(value, str):
-        return None
-    value = value.strip()
-    return value or None
+    return _parse_scalar(raw)
 
 
 def _build_group_manifest_slice(lines: list[str], item_indent: int) -> str:
@@ -332,3 +308,429 @@ def _find_block_end(
         if indent <= parent_indent:
             return index
     return end
+
+
+# --- authored outline: order, comments, disabled members (§3.1, §3.2) ---
+
+
+def _build_outline(lines: list[str], start_line: int) -> list[dict[str, Any]]:
+    top = _find_components_range(lines, 0, len(lines), max_indent=0)
+    if top is None:
+        return []
+    start, end = top
+    indent = _first_item_indent(lines, start, end)
+    if indent is None:
+        return []
+    return _parse_component_list(lines, start, end, indent, start_line)
+
+
+def iter_active_leaves(nodes: list[dict[str, Any]]) -> Iterator[dict[str, Any]]:
+    """Depth-first walk yielding non-disabled component/set nodes.
+
+    Mirrors the traversal order of `manifest.normalize_components`, so the
+    Nth node yielded here corresponds to the Nth entry of its flattened
+    component list.
+    """
+    for node in nodes:
+        if node.get("disabled"):
+            continue
+        if node["kind"] == "group":
+            yield from iter_active_leaves(node.get("children", []))
+        else:
+            yield node
+
+
+def _find_item_end(lines: list[str], start: int, end: int, parent_indent: int) -> int:
+    """Find where a component/member item's own span ends.
+
+    Unlike `_find_block_end` (used for group-slice text boundaries, which
+    treats every comment as trailing filler regardless of indent), this
+    stops at a same-or-shallower comment line too -- such a line is a
+    sibling's block comment or a disabled sibling, not this item's content.
+    """
+    for index in range(start, end):
+        line = lines[index]
+        stripped = line.strip()
+        if not stripped:
+            continue
+        indent = len(line) - len(line.lstrip(" \t"))
+        if indent <= parent_indent:
+            return index
+    return end
+
+
+def _first_item_indent(lines: list[str], start: int, end: int) -> int | None:
+    for index in range(start, end):
+        raw = lines[index].rstrip("\n")
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        m = _DASH_ITEM_RE.match(raw)
+        if m:
+            return len(m.group("indent"))
+        if stripped.startswith("#"):
+            continue
+        return None
+    return None
+
+
+def _parse_component_list(
+    lines: list[str],
+    start: int,
+    end: int,
+    indent: int,
+    start_line: int,
+) -> list[dict[str, Any]]:
+    nodes: list[dict[str, Any]] = []
+    index = start
+    order = 0
+    pending: list[tuple[int, str]] = []
+    while index < end:
+        raw = lines[index].rstrip("\n")
+        bare = raw.strip()
+        if not bare:
+            pending = []
+            index += 1
+            continue
+        line_indent = len(raw) - len(raw.lstrip(" "))
+        if line_indent != indent:
+            index += 1
+            continue
+
+        disabled_match = _DISABLED_ITEM_RE.match(raw)
+        if disabled_match:
+            item_end = _consume_disabled_block(lines, index, end, indent)
+            comment = _reduce_pending(pending)
+            pending = []
+            nodes.append(
+                _build_disabled_component_node(
+                    lines, index, item_end, start_line, order, comment
+                )
+            )
+            order += 1
+            index = item_end
+            continue
+
+        if bare.startswith("#"):
+            pending.append((start_line + index, bare.lstrip("#").strip()))
+            index += 1
+            continue
+
+        item_match = _DASH_ITEM_RE.match(raw)
+        if not item_match:
+            index += 1
+            continue
+
+        item_end = _find_item_end(lines, index + 1, end, indent)
+        comment = _reduce_pending(pending)
+        pending = []
+        nodes.append(
+            _build_component_node(lines, index, item_end, start_line, order, comment)
+        )
+        order += 1
+        index = item_end
+
+    return nodes
+
+
+def _consume_disabled_block(lines: list[str], start: int, end: int, indent: int) -> int:
+    index = start + 1
+    while index < end:
+        line = lines[index].rstrip("\n")
+        bare = line.strip()
+        if not bare:
+            break
+        line_indent = len(line) - len(line.lstrip(" \t"))
+        if bare.startswith("#") and line_indent >= indent:
+            index += 1
+            continue
+        break
+    return index
+
+
+def _reduce_pending(pending: list[tuple[int, str]]) -> dict[str, Any] | None:
+    if not pending:
+        return None
+    text = "\n".join(t for _, t in pending)
+    return {
+        "text": text,
+        "line_start": pending[0][0],
+        "line_end": pending[-1][0],
+    }
+
+
+def _disabled_raw_text(lines: list[str], start: int, end: int) -> str:
+    out = []
+    for index in range(start, end):
+        line = lines[index].rstrip("\n")
+        match = re.match(r"^ *#[ \t]?(?P<rest>.*)$", line)
+        out.append(match.group("rest") if match else line.strip())
+    return "\n".join(out)
+
+
+def _build_disabled_component_node(
+    lines: list[str],
+    start: int,
+    end: int,
+    start_line: int,
+    order: int,
+    comment: dict[str, Any] | None,
+) -> dict[str, Any]:
+    raw_text = _disabled_raw_text(lines, start, end)
+    kind, name = _classify_disabled_component(raw_text)
+    return {
+        "kind": kind,
+        "name": name,
+        "order": order,
+        "disabled": True,
+        "line_start": start_line + start,
+        "line_end": start_line + end - 1,
+        "comment": comment,
+        "inline_comment": None,
+        "members": {},
+        "children": [],
+        "raw": raw_text,
+    }
+
+
+def _classify_disabled_component(raw_text: str) -> tuple[str, str | None]:
+    first = raw_text.splitlines()[0].strip() if raw_text else ""
+    if first.startswith("-"):
+        first = first[1:].strip()
+    match = re.match(r"^(?P<key>[A-Za-z0-9_-]+)\s*:\s*(?P<value>.*)$", first)
+    if match and match.group("key") in _COMPONENT_KEY_NAMES:
+        key = match.group("key")
+        kind = "group" if key == "group" else ("set" if key == "set" else "component")
+        return kind, _parse_scalar(match.group("value"))
+    return "component", None
+
+
+def _build_component_node(
+    lines: list[str],
+    start: int,
+    end: int,
+    start_line: int,
+    order: int,
+    comment: dict[str, Any] | None,
+) -> dict[str, Any]:
+    first_line = lines[start].rstrip("\n")
+    _, inline_comment = _split_inline_comment(first_line)
+    indent = len(first_line) - len(first_line.lstrip(" "))
+    key, name = _detect_item_key(lines, start, end, indent)
+    line_start = start_line + start
+    line_end = start_line + end - 1
+
+    if key == "group":
+        children: list[dict[str, Any]] = []
+        child_range = _find_components_range(lines, start + 1, end, max_indent=None)
+        if child_range is not None:
+            child_start, child_end = child_range
+            child_indent = _first_item_indent(lines, child_start, child_end)
+            if child_indent is not None:
+                children = _parse_component_list(
+                    lines, child_start, child_end, child_indent, start_line
+                )
+        return {
+            "kind": "group",
+            "name": name,
+            "order": order,
+            "disabled": False,
+            "line_start": line_start,
+            "line_end": line_end,
+            "comment": comment,
+            "inline_comment": inline_comment,
+            "members": {},
+            "children": children,
+        }
+
+    kind = "set" if key == "set" else "component"
+    members = _parse_all_member_lists(lines, start, end, indent, start_line)
+    return {
+        "kind": kind,
+        "name": name,
+        "order": order,
+        "disabled": False,
+        "line_start": line_start,
+        "line_end": line_end,
+        "comment": comment,
+        "inline_comment": inline_comment,
+        "members": members,
+        "children": [],
+    }
+
+
+def _detect_item_key(
+    lines: list[str], start: int, end: int, indent: int
+) -> tuple[str, str | None]:
+    first_line = lines[start].rstrip("\n")
+    code, _ = _split_inline_comment(first_line)
+    match = re.match(r"^ *-\s*(?P<key>[A-Za-z0-9_-]+)\s*:\s*(?P<value>.*)$", code)
+    if match and match.group("key") in _COMPONENT_KEY_NAMES:
+        return match.group("key"), _parse_scalar(match.group("value"))
+
+    child_indent: int | None = None
+    for index in range(start + 1, end):
+        line = lines[index].rstrip("\n")
+        bare = line.strip()
+        if not bare or bare.startswith("#"):
+            continue
+        line_indent = len(line) - len(line.lstrip(" "))
+        if line_indent <= indent:
+            break
+        if child_indent is None:
+            child_indent = line_indent
+        if line_indent != child_indent:
+            continue
+        code, _ = _split_inline_comment(line)
+        match = re.match(r"^ *(?P<key>[A-Za-z0-9_-]+)\s*:\s*(?P<value>.*)$", code)
+        if match and match.group("key") in _COMPONENT_KEY_NAMES:
+            return match.group("key"), _parse_scalar(match.group("value"))
+
+    return "name", None
+
+
+def _parse_all_member_lists(
+    lines: list[str],
+    start: int,
+    end: int,
+    indent: int,
+    start_line: int,
+) -> dict[str, list[dict[str, Any]]]:
+    members: dict[str, list[dict[str, Any]]] = {}
+    for key in _MEMBER_KEYS:
+        list_range = _find_named_list_range(lines, start + 1, end, key, indent)
+        if list_range is None:
+            continue
+        list_start, list_end = list_range
+        item_indent = _first_item_indent(lines, list_start, list_end)
+        if item_indent is None:
+            continue
+        parsed = _parse_member_items(lines, list_start, list_end, item_indent, start_line)
+        if parsed:
+            members[key] = parsed
+    return members
+
+
+def _find_named_list_range(
+    lines: list[str],
+    start: int,
+    end: int,
+    key: str,
+    parent_indent: int,
+) -> tuple[int, int] | None:
+    pattern = re.compile(rf"^(?P<indent> *){key}\s*:\s*(?:#.*)?$")
+    for index in range(start, end):
+        line = lines[index].rstrip("\n")
+        match = pattern.match(line)
+        if not match:
+            continue
+        list_indent = len(match.group("indent"))
+        if list_indent <= parent_indent:
+            continue
+        return index + 1, _find_block_end(lines, index + 1, end, list_indent)
+    return None
+
+
+def _parse_member_items(
+    lines: list[str],
+    start: int,
+    end: int,
+    indent: int,
+    start_line: int,
+) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    index = start
+    order = 0
+    pending: list[tuple[int, str]] = []
+    while index < end:
+        raw = lines[index].rstrip("\n")
+        bare = raw.strip()
+        if not bare:
+            pending = []
+            index += 1
+            continue
+        line_indent = len(raw) - len(raw.lstrip(" "))
+        if line_indent != indent:
+            index += 1
+            continue
+
+        disabled_match = _DISABLED_ITEM_RE.match(raw)
+        if disabled_match:
+            item_end = _consume_disabled_block(lines, index, end, indent)
+            comment = _reduce_pending(pending)
+            pending = []
+            items.append(
+                {
+                    "order": order,
+                    "disabled": True,
+                    "line_start": start_line + index,
+                    "line_end": start_line + item_end - 1,
+                    "comment": comment,
+                    "inline_comment": None,
+                    "raw": _disabled_raw_text(lines, index, item_end),
+                }
+            )
+            order += 1
+            index = item_end
+            continue
+
+        if bare.startswith("#"):
+            pending.append((start_line + index, bare.lstrip("#").strip()))
+            index += 1
+            continue
+
+        item_match = _DASH_ITEM_RE.match(raw)
+        if not item_match:
+            index += 1
+            continue
+
+        item_end = _find_item_end(lines, index + 1, end, indent)
+        _, inline_comment = _split_inline_comment(raw)
+        comment = _reduce_pending(pending)
+        pending = []
+        items.append(
+            {
+                "order": order,
+                "disabled": False,
+                "line_start": start_line + index,
+                "line_end": start_line + item_end - 1,
+                "comment": comment,
+                "inline_comment": inline_comment,
+            }
+        )
+        order += 1
+        index = item_end
+
+    return items
+
+
+def _split_inline_comment(line: str) -> tuple[str, str | None]:
+    in_single = False
+    in_double = False
+    for index, ch in enumerate(line):
+        if in_single:
+            if ch == "'":
+                in_single = False
+        elif in_double:
+            if ch == '"':
+                in_double = False
+        elif ch == "'":
+            in_single = True
+        elif ch == '"':
+            in_double = True
+        elif ch == "#" and (index == 0 or line[index - 1] in " \t"):
+            code = line[:index].rstrip()
+            comment = line[index + 1 :].strip()
+            return code, (comment or None)
+    return line, None
+
+
+def _parse_scalar(raw: str) -> str | None:
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        value = yaml.safe_load(raw)
+    except Exception:
+        return raw
+    return value if isinstance(value, str) else raw
diff --git a/tests/test_hydrate_plugins.py b/tests/test_hydrate_plugins.py
index 46096e7..9f8ee88 100644
--- a/tests/test_hydrate_plugins.py
+++ b/tests/test_hydrate_plugins.py
@@ -1537,6 +1537,73 @@ def test_hydrate_source_manifest_preserves_format_and_group_manifest(
     }
 
 
+def test_hydrate_outline_records_order_comments_and_disabled_members(
+    tmp_path: Path,
+) -> None:
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  # curated notes
+  - name: notes
+    files:
+      - notes/a.md
+      - notes/b.md  # keeper
+      # - notes/c.md
+
+  # - name: dropped
+  #   files:
+  #     - notes/d.md
+""",
+        encoding="utf-8",
+    )
+    (tmp_path / "notes").mkdir()
+    (tmp_path / "notes" / "a.md").write_text("a", encoding="utf-8")
+    (tmp_path / "notes" / "b.md").write_text("b", encoding="utf-8")
+
+    plan = build_hydration_plan(
+        str(manifest_path),
+        overrides=HydrateOverrides(),
+        cwd=str(tmp_path),
+    )
+    apply_hydration_plan(plan)
+
+    root_manifest = (context_dir / "manifest.yaml").read_text(encoding="utf-8")
+    assert "# - notes/c.md" in root_manifest
+    assert "# - name: dropped" in root_manifest
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    outline = index_json["outline"]
+    assert [node["kind"] for node in outline] == ["component", "component"]
+
+    notes_node, dropped_node = outline
+    assert notes_node["name"] == "notes"
+    assert notes_node["order"] == 0
+    assert notes_node["disabled"] is False
+    assert notes_node["comment"]["text"] == "curated notes"
+
+    files = notes_node["members"]["files"]
+    assert [member["disabled"] for member in files] == [False, False, True]
+    assert files[1]["inline_comment"] == "keeper"
+    assert files[2]["raw"] == "- notes/c.md"
+
+    assert dropped_node["name"] == "dropped"
+    assert dropped_node["disabled"] is True
+    assert dropped_node["order"] == 1
+    assert "notes/d.md" in dropped_node["raw"]
+
+    # disabled members produce no payload and are never resolved
+    assert not (context_dir / "notes" / "c.md").exists()
+    assert not (context_dir / "dropped").exists()
+    assert set(index_json["components"].keys()) == {"notes"}
+
+
 def test_hydrate_data_manifest_omits_manifest_source(tmp_path: Path) -> None:
     context_dir = tmp_path / "ctx"
     plan = build_hydration_plan_data(
diff --git a/tests/test_manifest_source.py b/tests/test_manifest_source.py
index 588590b..3f4b751 100644
--- a/tests/test_manifest_source.py
+++ b/tests/test_manifest_source.py
@@ -71,8 +71,8 @@ def test_load_manifest_source_preserves_group_slices(tmp_path: Path) -> None:
     source = load_manifest_source(path)
 
     assert source.source_format is not None
-    assert "# - name: skipped" not in source.source_format.body
-    assert "not hydrated" not in source.source_format.body
+    assert "# - name: skipped" in source.source_format.body
+    assert "not hydrated" in source.source_format.body
     assert "# speech materials" in source.source_format.body
     speech_slice = source.source_format.group_slices[("speech",)]
     assert speech_slice.line == 6
@@ -82,9 +82,32 @@ def test_load_manifest_source_preserves_group_slices(tmp_path: Path) -> None:
         "    components:\n"
         "      - name: anchor  # main voice note\n"
         "        text: hello\n"
+        "      # - name: skipped\n"
+        "      #   text: not hydrated\n"
         "\n"
     )
 
+    outline = source.source_format.outline
+    assert [node["kind"] for node in outline] == ["group", "component"]
+    speech_group = outline[0]
+    assert speech_group["name"] == "speech"
+    assert speech_group["order"] == 0
+    assert speech_group["comment"] == {
+        "text": "speech materials",
+        "line_start": 5,
+        "line_end": 5,
+    }
+    anchor, skipped = speech_group["children"]
+    assert anchor["name"] == "anchor"
+    assert anchor["disabled"] is False
+    assert anchor["inline_comment"] == "main voice note"
+    assert skipped["name"] == "skipped"
+    assert skipped["disabled"] is True
+    assert skipped["raw"] == "- name: skipped\n  text: not hydrated"
+    refs = outline[1]
+    assert refs["name"] == "refs"
+    assert refs["order"] == 1
+
 
 def test_load_manifest_text_rejects_text_without_manifest() -> None:
     with pytest.raises(ValueError, match="No contextualize manifest found"):

From 283385cab3a26d59fd5867b037f0caa5985068ae Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:31:25 -0400
Subject: [PATCH 2/6] feat(manifest): support ordered sets that fuse into one
 unit

`- set: NAME` sits alongside `name:`/`group:` in component position:
an ordered run of `files:` members that resolves to ONE hydrated
file instead of one-per-source, addressable by name like any other
component. Parts are concatenated in authored order behind a part
boundary header carrying the source key, title (explicit `comment:`
or the member's trailing `#` comment), and timestamps where known;
the boundaries are also recorded structurally in index.json.

Groups may contain sets; sets may not contain groups, repos, or
manifests (fusion only makes sense over resolvable file content).
---
 src/contextualize/manifest/hydrate.py  | 297 ++++++++++++++++++-------
 src/contextualize/manifest/manifest.py |  38 +++-
 tests/test_hydrate_plugins.py          |  93 ++++++++
 tests/test_manifest_normalize.py       |  65 ++++++
 4 files changed, 410 insertions(+), 83 deletions(-)
 create mode 100644 tests/test_manifest_normalize.py

diff --git a/src/contextualize/manifest/hydrate.py b/src/contextualize/manifest/hydrate.py
index a5687cd..0283e26 100644
--- a/src/contextualize/manifest/hydrate.py
+++ b/src/contextualize/manifest/hydrate.py
@@ -39,10 +39,16 @@
 from .manifest import (
     GROUP_BASE_KEY,
     GROUP_PATH_KEY,
+    SET_KEY,
     coerce_file_spec,
     normalize_components,
 )
-from .source import ManifestFormat, ManifestSlice, load_manifest_source
+from .source import (
+    ManifestFormat,
+    ManifestSlice,
+    iter_active_leaves,
+    load_manifest_source,
+)
 
 _EXTERNAL_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 _SOURCE_IGNORE_PATTERNS = [
@@ -510,9 +516,20 @@ def build_hydration_plan_data(
             context_cfg["agents_text"],
         )
 
+    active_outline_nodes: list[dict[str, Any]] = (
+        list(iter_active_leaves(manifest_format.outline))
+        if manifest_format is not None
+        else []
+    )
+
     log_progress("hydrate", "component", "total", count=len(components))
-    for comp in components:
+    for comp_index, comp in enumerate(components):
         comp_name = comp["name"]
+        outline_node = (
+            active_outline_nodes[comp_index]
+            if comp_index < len(active_outline_nodes)
+            else None
+        )
         log_progress("hydrate", "component", "start", target=comp_name)
         comp_files = comp.get("files")
         comp_repos = comp.get("repos")
@@ -778,44 +795,120 @@ def build_hydration_plan_data(
                 effective_strip_prefix = global_strip_prefix
                 skip_external_root = False
 
-            for (
-                item,
-                content,
-                suffix,
-                ranges,
-                symbols,
-                range_spec,
-                spec_comment,
-                file_opts,
-                spec_root,
-            ) in resolved_items:
-                rel_path, should_write = _resolve_context_path(
-                    comp_name,
+            if comp.get(SET_KEY):
+                set_rel_path = _dedupe_path(
+                    _build_set_output_path(
+                        comp_name,
+                        comp.get(GROUP_PATH_KEY),
+                        comp.get(GROUP_BASE_KEY),
+                    ),
+                    used_paths,
+                )
+                _ensure_relative(set_rel_path)
+                fused_text, parts = _build_set_fusion(resolved_items, outline_node)
+                files_to_write.append((context_dir / set_rel_path, fused_text))
+                index_components.setdefault(comp_name, []).append(
+                    _build_set_index_entry(set_rel_path, fused_text, parts)
+                )
+                if outline_node is not None:
+                    outline_node["set"] = {
+                        "context_path": set_rel_path.as_posix(),
+                        "parts": parts,
+                    }
+                normalized_files.extend(
+                    _build_manifest_file_entry(
+                        item, range_spec, symbols, spec_comment, file_opts
+                    )
+                    for (
+                        item,
+                        _content,
+                        _suffix,
+                        _ranges,
+                        symbols,
+                        range_spec,
+                        spec_comment,
+                        file_opts,
+                        _spec_root,
+                    ) in resolved_items
+                )
+            else:
+                for (
                     item,
+                    content,
                     suffix,
-                    used_paths,
-                    identity_paths,
-                    context_cfg["path_strategy"],
                     ranges,
                     symbols,
-                    component_root=component_root,
-                    use_external_root=use_external_root,
-                    strip_prefix=effective_strip_prefix,
-                    skip_external_root=skip_external_root,
-                    external_root_prefix=spec_root,
-                )
-                plugin_identity = _plugin_pending_key(item, ranges, symbols)
-                if plugin_identity is not None:
-                    plugin_pending.setdefault(plugin_identity, []).append(
-                        _PluginPendingWrite(
-                            rel_path=rel_path,
-                            content=content,
-                            should_write=should_write,
-                            item=item,
-                            encounter_index=plugin_seen_counter,
-                        )
+                    range_spec,
+                    spec_comment,
+                    file_opts,
+                    spec_root,
+                ) in resolved_items:
+                    rel_path, should_write = _resolve_context_path(
+                        comp_name,
+                        item,
+                        suffix,
+                        used_paths,
+                        identity_paths,
+                        context_cfg["path_strategy"],
+                        ranges,
+                        symbols,
+                        component_root=component_root,
+                        use_external_root=use_external_root,
+                        strip_prefix=effective_strip_prefix,
+                        skip_external_root=skip_external_root,
+                        external_root_prefix=spec_root,
                     )
-                    plugin_seen_counter += 1
+                    plugin_identity = _plugin_pending_key(item, ranges, symbols)
+                    if plugin_identity is not None:
+                        plugin_pending.setdefault(plugin_identity, []).append(
+                            _PluginPendingWrite(
+                                rel_path=rel_path,
+                                content=content,
+                                should_write=should_write,
+                                item=item,
+                                encounter_index=plugin_seen_counter,
+                            )
+                        )
+                        plugin_seen_counter += 1
+                        index_components.setdefault(comp_name, []).append(
+                            _build_index_entry(
+                                rel_path,
+                                item,
+                                ranges,
+                                symbols,
+                                content,
+                            )
+                        )
+                        normalized_files.append(
+                            _build_manifest_file_entry(
+                                item,
+                                range_spec,
+                                symbols,
+                                spec_comment,
+                                file_opts,
+                            )
+                        )
+                        continue
+                    if should_write:
+                        _queue_hydrated_file(
+                            context_dir / rel_path,
+                            item,
+                            content,
+                            copy_files=context_cfg["copy"],
+                            ranges=ranges,
+                            symbols=symbols,
+                            files_to_write=files_to_write,
+                            files_to_copy=files_to_copy,
+                            files_to_symlink=files_to_symlink,
+                        )
+                        file_ts = _item_file_ts(item)
+                        if file_ts:
+                            file_timestamps[context_dir / rel_path] = file_ts
+                        dir_ts = _item_dir_ts(item)
+                        if dir_ts:
+                            file_timestamps.setdefault(
+                                (context_dir / rel_path).parent, dir_ts
+                            )
                     index_components.setdefault(comp_name, []).append(
                         _build_index_entry(
                             rel_path,
@@ -834,45 +927,6 @@ def build_hydration_plan_data(
                             file_opts,
                         )
                     )
-                    continue
-                if should_write:
-                    _queue_hydrated_file(
-                        context_dir / rel_path,
-                        item,
-                        content,
-                        copy_files=context_cfg["copy"],
-                        ranges=ranges,
-                        symbols=symbols,
-                        files_to_write=files_to_write,
-                        files_to_copy=files_to_copy,
-                        files_to_symlink=files_to_symlink,
-                    )
-                    file_ts = _item_file_ts(item)
-                    if file_ts:
-                        file_timestamps[context_dir / rel_path] = file_ts
-                    dir_ts = _item_dir_ts(item)
-                    if dir_ts:
-                        file_timestamps.setdefault(
-                            (context_dir / rel_path).parent, dir_ts
-                        )
-                index_components.setdefault(comp_name, []).append(
-                    _build_index_entry(
-                        rel_path,
-                        item,
-                        ranges,
-                        symbols,
-                        content,
-                    )
-                )
-                normalized_files.append(
-                    _build_manifest_file_entry(
-                        item,
-                        range_spec,
-                        symbols,
-                        spec_comment,
-                        file_opts,
-                    )
-                )
 
         if comp_manifests:
             from .contexts import ensure_manifest_link_hydrated
@@ -1389,10 +1443,14 @@ def _build_normalized_component(comp: dict[str, Any], name: str) -> dict[str, An
     normalized = {
         k: v
         for k, v in comp.items()
-        if k not in {"files", "repos", "name", GROUP_PATH_KEY, GROUP_BASE_KEY}
+        if k
+        not in {"files", "repos", "name", GROUP_PATH_KEY, GROUP_BASE_KEY, SET_KEY}
         and v is not None
     }
-    normalized["name"] = name
+    if comp.get(SET_KEY):
+        normalized["set"] = name
+    else:
+        normalized["name"] = name
     return normalized
 
 
@@ -2379,6 +2437,93 @@ def _build_component_root(
     return Path(component_name)
 
 
+def _build_set_output_path(
+    component_name: str,
+    group_path: Any | None,
+    base_name: Any | None,
+) -> Path:
+    if group_path:
+        parts = [group_path] if isinstance(group_path, str) else list(group_path)
+        name = base_name if isinstance(base_name, str) and base_name else component_name
+        return Path(*parts, f"{name}.md")
+    return Path(f"{component_name}.md")
+
+
+def _format_set_part_header(item: ResolvedItem, title: str | None) -> str:
+    bits = [item.manifest_spec]
+    if title:
+        bits.append(title)
+    timestamp = item.source_modified or item.source_created
+    if timestamp:
+        bits.append(timestamp)
+    return f"--- {' · '.join(bits)} ---"
+
+
+def _set_member_titles(outline_node: dict[str, Any] | None) -> list[str | None]:
+    if outline_node is None:
+        return []
+    files = outline_node.get("members", {}).get("files", [])
+    return [member["inline_comment"] for member in files if not member["disabled"]]
+
+
+def _build_set_fusion(
+    resolved_items: list[
+        tuple[
+            ResolvedItem,
+            str,
+            str | None,
+            list[tuple[int, int]] | None,
+            list[str] | None,
+            list[tuple[int, int]] | None,
+            str | None,
+            dict[str, Any],
+            str | None,
+        ]
+    ],
+    outline_node: dict[str, Any] | None = None,
+) -> tuple[str, list[dict[str, Any]]]:
+    member_titles = _set_member_titles(outline_node)
+    parts: list[dict[str, Any]] = []
+    blocks: list[str] = []
+    line_cursor = 1
+    for order, (item, content, *_rest) in enumerate(resolved_items):
+        spec_comment = _rest[4]
+        title = spec_comment or (
+            member_titles[order] if order < len(member_titles) else None
+        )
+        header = _format_set_part_header(item, title)
+        body = content if content.endswith("\n") else f"{content}\n"
+        block = f"{header}\n\n{body}"
+        line_start = line_cursor
+        line_end = line_start + block.count("\n") - 1
+        line_cursor = line_end + 2
+        blocks.append(block)
+        parts.append(
+            {
+                "order": order,
+                "key": item.manifest_spec,
+                "title": title,
+                "source_created": item.source_created,
+                "source_modified": item.source_modified,
+                "line_start": line_start,
+                "line_end": line_end,
+            }
+        )
+    return "\n".join(blocks), parts
+
+
+def _build_set_index_entry(
+    rel_path: Path, fused_text: str, parts: list[dict[str, Any]]
+) -> dict[str, Any]:
+    digest = hashlib.sha256(fused_text.encode("utf-8")).hexdigest()
+    return {
+        "context_path": rel_path.as_posix(),
+        "kind": "set",
+        "hash": f"sha256:{digest}",
+        "parts": parts,
+    }
+
+
 def _resolve_context_path(
     component_name: str,
     item: ResolvedItem,
diff --git a/src/contextualize/manifest/manifest.py b/src/contextualize/manifest/manifest.py
index 5dddf1d..0f6ff30 100644
--- a/src/contextualize/manifest/manifest.py
+++ b/src/contextualize/manifest/manifest.py
@@ -4,6 +4,7 @@
 GROUP_DELIMITER = "."
 GROUP_PATH_KEY = "__group_path"
 GROUP_BASE_KEY = "__group_base"
+SET_KEY = "__is_set"
 
 _DEFAULT_KEYS = {
     "wrap",
@@ -62,34 +63,55 @@ def collect_group_defaults(entry: dict[str, Any]) -> dict[str, Any]:
         return defaults
 
     def add_component(
-        entry: dict[str, Any], group_path: list[str], defaults: dict[str, Any]
+        entry: dict[str, Any],
+        group_path: list[str],
+        defaults: dict[str, Any],
+        *,
+        is_set: bool = False,
     ) -> None:
+        kind = "Set" if is_set else "Component"
         if "group" in entry:
-            raise ValueError("Component cannot define 'group'")
+            raise ValueError(f"{kind} cannot define 'group'")
         if "components" in entry:
-            raise ValueError("Component cannot define 'components' without 'group'")
+            raise ValueError(f"{kind} cannot define 'components' without 'group'")
 
         comp = dict(entry)
-        name = comp.get("name")
+        if is_set:
+            if "name" in comp:
+                raise ValueError("Set cannot also define 'name'")
+            name = comp.pop("set")
+        else:
+            name = comp.get("name")
         if name is None:
             name = next_auto_name()
         if not isinstance(name, str):
-            raise ValueError("Component name must be a string")
+            raise ValueError(f"{kind} name must be a string")
         name = name.strip()
         if not name:
-            raise ValueError("Component name must be a non-empty string")
-        validate_name(name, kind="Component name", allow_delimiter=True)
+            raise ValueError(f"{kind} name must be a non-empty string")
+        validate_name(name, kind=f"{kind} name", allow_delimiter=True)
 
         full_name = join_group_name(group_path, name)
         if full_name in used_names:
             raise ValueError(f"Duplicate component name: {full_name}")
         used_names.add(full_name)
 
+        if is_set:
+            for unsupported in ("repos", "manifests"):
+                if unsupported in comp:
+                    raise ValueError(
+                        f"Set '{full_name}' does not support '{unsupported}'"
+                    )
+            if not comp.get("files"):
+                raise ValueError(f"Set '{full_name}' must define 'files'")
+
         for key, value in defaults.items():
             if key not in comp:
                 comp[key] = value
 
         comp["name"] = full_name
+        if is_set:
+            comp[SET_KEY] = True
         if group_path:
             comp[GROUP_PATH_KEY] = tuple(group_path)
             comp[GROUP_BASE_KEY] = name
@@ -127,6 +149,8 @@ def process(
                 merged_defaults = dict(defaults)
                 merged_defaults.update(group_defaults)
                 process(group_components, group_path + [group_name], merged_defaults)
+            elif "set" in entry:
+                add_component(entry, group_path, defaults, is_set=True)
             else:
                 add_component(entry, group_path, defaults)
 
diff --git a/tests/test_hydrate_plugins.py b/tests/test_hydrate_plugins.py
index 9f8ee88..4a4814e 100644
--- a/tests/test_hydrate_plugins.py
+++ b/tests/test_hydrate_plugins.py
@@ -1604,6 +1604,99 @@ def test_hydrate_outline_records_order_comments_and_disabled_members(
     assert set(index_json["components"].keys()) == {"notes"}
 
 
+def test_hydrate_set_fuses_members_into_one_addressable_file(
+    tmp_path: Path,
+) -> None:
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    (tmp_path / "a.md").write_text("alpha body", encoding="utf-8")
+    (tmp_path / "b.md").write_text("beta body", encoding="utf-8")
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  - set: jul-7 run
+    files:
+      - a.md  # first note
+      - b.md
+""",
+        encoding="utf-8",
+    )
+
+    plan = build_hydration_plan(
+        str(manifest_path),
+        overrides=HydrateOverrides(),
+        cwd=str(tmp_path),
+    )
+    apply_hydration_plan(plan)
+
+    fused_path = context_dir / "jul-7 run.md"
+    assert fused_path.exists()
+    fused = fused_path.read_text(encoding="utf-8")
+    assert fused.index("alpha body") < fused.index("beta body")
+    assert "--- a.md · first note ---" in fused
+    assert "--- b.md ---" in fused
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    set_entries = index_json["components"]["jul-7 run"]
+    assert len(set_entries) == 1
+    assert set_entries[0]["kind"] == "set"
+    assert set_entries[0]["context_path"] == "jul-7 run.md"
+    parts = set_entries[0]["parts"]
+    assert [part["key"] for part in parts] == ["a.md", "b.md"]
+    assert parts[0]["title"] == "first note"
+    assert parts[0]["line_start"] == 1
+    assert parts[1]["line_start"] > parts[0]["line_end"]
+
+    outline_set_node = index_json["outline"][0]
+    assert outline_set_node["kind"] == "set"
+    assert outline_set_node["name"] == "jul-7 run"
+    assert outline_set_node["set"]["context_path"] == "jul-7 run.md"
+    assert outline_set_node["set"]["parts"] == parts
+
+
+def test_hydrate_group_may_contain_set_alongside_plain_component(
+    tmp_path: Path,
+) -> None:
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    (tmp_path / "a.md").write_text("alpha", encoding="utf-8")
+    (tmp_path / "p.md").write_text("plain", encoding="utf-8")
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  - group: g
+    components:
+      - set: fused
+        files:
+          - a.md
+      - name: plain
+        files:
+          - p.md
+""",
+        encoding="utf-8",
+    )
+
+    plan = build_hydration_plan(
+        str(manifest_path),
+        overrides=HydrateOverrides(),
+        cwd=str(tmp_path),
+    )
+    apply_hydration_plan(plan)
+
+    assert (context_dir / "g" / "fused.md").exists()
+    assert (context_dir / "g" / "plain" / "p.md").exists()
+
+
 def test_hydrate_data_manifest_omits_manifest_source(tmp_path: Path) -> None:
     context_dir = tmp_path / "ctx"
     plan = build_hydration_plan_data(
diff --git a/tests/test_manifest_normalize.py b/tests/test_manifest_normalize.py
new file mode 100644
index 0000000..bbbdf3e
--- /dev/null
+++ b/tests/test_manifest_normalize.py
@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import pytest
+
+from contextualize.manifest.manifest import GROUP_BASE_KEY, GROUP_PATH_KEY, SET_KEY, normalize_components
+
+
+def test_normalize_components_recognizes_top_level_set() -> None:
+    normalized = normalize_components(
+        [{"set": "jul-7 run", "files": ["a.md", "b.md"]}]
+    )
+
+    assert len(normalized) == 1
+    comp = normalized[0]
+    assert comp["name"] == "jul-7 run"
+    assert comp[SET_KEY] is True
+    assert comp["files"] == ["a.md", "b.md"]
+
+
+def test_normalize_components_group_may_contain_set() -> None:
+    normalized = normalize_components(
+        [
+            {
+                "group": "g",
+                "components": [
+                    {"set": "fused", "files": ["a.md"]},
+                    {"name": "plain", "files": ["b.md"]},
+                ],
+            }
+        ]
+    )
+
+    names = [comp["name"] for comp in normalized]
+    assert names == ["g.fused", "g.plain"]
+    fused = normalized[0]
+    assert fused[SET_KEY] is True
+    assert fused[GROUP_PATH_KEY] == ("g",)
+    assert fused[GROUP_BASE_KEY] == "fused"
+
+
+def test_normalize_components_set_cannot_contain_group() -> None:
+    with pytest.raises(ValueError, match="invalid keys"):
+        normalize_components(
+            [{"set": "x", "files": ["a.md"], "group": "y", "components": []}]
+        )
+
+
+def test_normalize_components_set_cannot_also_define_name() -> None:
+    with pytest.raises(ValueError, match="cannot also define 'name'"):
+        normalize_components([{"set": "x", "name": "y", "files": ["a.md"]}])
+
+
+def test_normalize_components_set_rejects_repos_and_manifests() -> None:
+    with pytest.raises(ValueError, match="does not support 'repos'"):
+        normalize_components([{"set": "x", "files": ["a.md"], "repos": ["b"]}])
+
+    with pytest.raises(ValueError, match="does not support 'manifests'"):
+        normalize_components(
+            [{"set": "x", "files": ["a.md"], "manifests": ["b.yaml"]}]
+        )
+
+
+def test_normalize_components_set_requires_files() -> None:
+    with pytest.raises(ValueError, match="must define 'files'"):
+        normalize_components([{"set": "x", "text": "hello"}])

From 18e41018b232f0cf5f11cd44869ac24618b5dab2 Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:38:19 -0400
Subject: [PATCH 3/6] feat(hydrate): recognize manifest references under files:
 and record edges

`manifests:` keeps meaning full inclusion; a `files:` entry that
happens to be a manifest is now recognized (registry membership,
`ctx/manifest` frontmatter tag, or a parseable fenced/whole-document
manifest, checked cheapest-first since registry membership can shell
out to zk) and recorded as a followable edge without changing its
payload -- the authored note still hydrates as an ordinary file copy.

Both forms land in index.json under `references.out`, each entry
stating its form, detection tier, and whether the payload is a live
pointer (full inclusion, symlinked to the linked context) or a
resolved copy (recognized reference, the note's own file content).
Relation naming and the inbound half of the edge (which needs a
registry-wide join across multiple contexts' indexes) are left to the
serving-surface round; each index already carries what that join
needs (source_path/source_ref per member, target_path per edge).
---
 src/contextualize/manifest/hydrate.py | 112 +++++++++++++++-
 src/contextualize/manifest/source.py  |  23 ++++
 tests/test_hydrate_plugins.py         | 177 ++++++++++++++++++++++++++
 3 files changed, 311 insertions(+), 1 deletion(-)

diff --git a/src/contextualize/manifest/hydrate.py b/src/contextualize/manifest/hydrate.py
index 0283e26..77815dc 100644
--- a/src/contextualize/manifest/hydrate.py
+++ b/src/contextualize/manifest/hydrate.py
@@ -9,7 +9,7 @@
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 from urllib.parse import unquote, urlparse
 
 from ..concurrency import run_indexed_tasks_fail_fast
@@ -46,10 +46,14 @@
 from .source import (
     ManifestFormat,
     ManifestSlice,
+    frontmatter_has_manifest_tag,
     iter_active_leaves,
     load_manifest_source,
+    path_contains_manifest,
 )
 
+_MANIFEST_REFERENCE_EXTENSIONS = {".md", ".markdown", ".yaml", ".yml"}
+
 _EXTERNAL_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 _SOURCE_IGNORE_PATTERNS = [
     ".context/",
@@ -503,6 +507,13 @@ def build_hydration_plan_data(
     plugin_seen_counter = 0
     resolved_spec_cache: dict[tuple[Any, ...], list[ResolvedItem]] = {}
     linked_manifest_failures: list[LinkedManifestFailure] = []
+    reference_edges: list[dict[str, Any]] = []
+    registry_sources_cache: list[set[Path]] = []
+
+    def get_registry_sources() -> set[Path]:
+        if not registry_sources_cache:
+            registry_sources_cache.append(_load_registry_manifest_sources())
+        return registry_sources_cache[0]
 
     global_strip_prefix: Path | None = None
     if context_cfg["path_strategy"] == "by-component":
@@ -612,6 +623,7 @@ def build_hydration_plan_data(
                     str | None,
                     dict[str, Any],
                     str | None,
+                    bool,
                 ]
             ] = []
             spec_jobs = get_payload_spec_jobs()
@@ -767,6 +779,7 @@ def build_hydration_plan_data(
                         extract_ranges(item.content, ranges) if ranges else item.content
                     )
                     suffix = _build_suffix(ranges, symbols)
+                    from_files = not spec_cache_key[1]
                     resolved_items.append(
                         (
                             item,
@@ -778,6 +791,7 @@ def build_hydration_plan_data(
                             spec_comment,
                             file_opts,
                             spec_root,
+                            from_files,
                         )
                     )
 
@@ -829,6 +843,7 @@ def build_hydration_plan_data(
                         spec_comment,
                         file_opts,
                         _spec_root,
+                        _from_files,
                     ) in resolved_items
                 )
             else:
@@ -842,6 +857,7 @@ def build_hydration_plan_data(
                     spec_comment,
                     file_opts,
                     spec_root,
+                    from_files,
                 ) in resolved_items:
                     rel_path, should_write = _resolve_context_path(
                         comp_name,
@@ -858,6 +874,14 @@ def build_hydration_plan_data(
                         skip_external_root=skip_external_root,
                         external_root_prefix=spec_root,
                     )
+                    if from_files:
+                        _record_recognized_reference(
+                            reference_edges,
+                            component_name=comp_name,
+                            item=item,
+                            context_path=rel_path,
+                            registry_sources=get_registry_sources,
+                        )
                     plugin_identity = _plugin_pending_key(item, ranges, symbols)
                     if plugin_identity is not None:
                         plugin_pending.setdefault(plugin_identity, []).append(
@@ -990,6 +1014,17 @@ def build_hydration_plan_data(
                 dest_rel = _dedupe_path(manifest_root / slug, used_paths)
                 _ensure_relative(dest_rel)
                 dirs_to_symlink.append((context_dir / dest_rel, canonical_dir))
+                reference_edges.append(
+                    {
+                        "component": comp_name,
+                        "form": "full",
+                        "spec": str(manifest_spec),
+                        "target_path": str(resolved_link_path),
+                        "detected_via": "manifests-key",
+                        "payload": "pointer",
+                        "context_path": dest_rel.as_posix(),
+                    }
+                )
 
         if normalized_files:
             normalized_comp["files"] = _dedupe_manifest_entries(normalized_files)
@@ -1062,6 +1097,8 @@ def build_hydration_plan_data(
             index_data["manifest_source"] = manifest_source
         if manifest_format is not None and manifest_format.outline:
             index_data["outline"] = manifest_format.outline
+        if reference_edges:
+            index_data["references"] = {"out": reference_edges}
         index_text = _dump_index(index_data)
         files_to_write.append((context_dir / "index.json", index_text))
 
@@ -1650,6 +1687,79 @@ def _find_global_subpath_prefix(
     return _find_common_subpath_prefix(all_subpaths)
 
 
+def _record_recognized_reference(
+    edges: list[dict[str, Any]],
+    *,
+    component_name: str,
+    item: ResolvedItem,
+    context_path: Path,
+    registry_sources: Callable[[], set[Path]],
+) -> None:
+    if item.source_type != "local" or not item.source_full_path:
+        return
+    path = Path(item.source_full_path)
+    if path.suffix.lower() not in _MANIFEST_REFERENCE_EXTENSIONS:
+        return
+    detected_via = _detect_manifest_reference(path, registry_sources)
+    if detected_via is None:
+        return
+    edges.append(
+        {
+            "component": component_name,
+            "form": "recognized",
+            "spec": item.manifest_spec,
+            "target_path": str(path),
+            "detected_via": detected_via,
+            "payload": "copy",
+            "context_path": context_path.as_posix(),
+        }
+    )
+
+
+def _detect_manifest_reference(
+    path: Path, registry_sources: Callable[[], set[Path]]
+) -> str | None:
+    # registry_sources() can shell out to zk; local checks must run first
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        text = None
+    if text is not None and frontmatter_has_manifest_tag(text):
+        return "frontmatter-tag"
+    if path_contains_manifest(path):
+        return "fenced-block"
+    try:
+        resolved = path.resolve()
+    except OSError:
+        resolved = path
+    if resolved in registry_sources():
+        return "registry"
+    return None
+
+
+def _load_registry_manifest_sources() -> set[Path]:
+    from .contexts import load_context_registry
+
+    sources: set[Path] = set()
+    try:
+        registry = load_context_registry()
+    except Exception:
+        return sources
+    for entry in registry.values():
+        manifest = entry.manifest if isinstance(entry.manifest, dict) else {}
+        raw_source = manifest.get("source")
+        if not isinstance(raw_source, str) or not raw_source:
+            continue
+        candidate = Path(os.path.expanduser(raw_source))
+        if not candidate.is_absolute():
+            candidate = entry.target_dir / candidate
+        try:
+            sources.add(candidate.resolve(strict=False))
+        except OSError:
+            continue
+    return sources
+
+
 def _manifest_has_local_sources(components: list[dict[str, Any]]) -> bool:
     for comp in components:
         files = comp.get("files")
diff --git a/src/contextualize/manifest/source.py b/src/contextualize/manifest/source.py
index 4f8a3dc..6a7a63a 100644
--- a/src/contextualize/manifest/source.py
+++ b/src/contextualize/manifest/source.py
@@ -147,6 +147,29 @@ def path_contains_manifest(path: str | os.PathLike[str]) -> bool:
     return True
 
 
+def frontmatter_has_manifest_tag(text: str, *, tag: str = "ctx/manifest") -> bool:
+    """Recognition tier for §3.4: a `ctx/manifest` tag in YAML frontmatter."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return False
+    try:
+        end_index = next(
+            index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---"
+        )
+    except StopIteration:
+        return False
+    try:
+        frontmatter = yaml.safe_load("\n".join(lines[1:end_index])) or {}
+    except Exception:
+        return False
+    if not isinstance(frontmatter, dict):
+        return False
+    tags = frontmatter.get("tags")
+    if not isinstance(tags, list):
+        return False
+    return any(isinstance(candidate, str) and candidate.strip() == tag for candidate in tags)
+
+
 def _load_nix_manifest_source(path: Path, cwd: str) -> dict[str, Any]:
     try:
         result = subprocess.run(
diff --git a/tests/test_hydrate_plugins.py b/tests/test_hydrate_plugins.py
index 4a4814e..7fa62bc 100644
--- a/tests/test_hydrate_plugins.py
+++ b/tests/test_hydrate_plugins.py
@@ -1697,6 +1697,183 @@ def test_hydrate_group_may_contain_set_alongside_plain_component(
     assert (context_dir / "g" / "plain" / "p.md").exists()
 
 
+def test_hydrate_recognizes_manifest_reference_via_frontmatter_tag(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / "ref-note.md").write_text(
+        """---
+title: sub ctx
+tags:
+  - ctx/manifest
+---
+
+```yaml
+components:
+  - name: main
+    text: hello
+```
+""",
+        encoding="utf-8",
+    )
+    (tmp_path / "plain.md").write_text("just a note, not a manifest", encoding="utf-8")
+
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  - name: refs
+    files:
+      - ref-note.md
+      - plain.md
+""",
+        encoding="utf-8",
+    )
+
+    plan = build_hydration_plan(
+        str(manifest_path), overrides=HydrateOverrides(), cwd=str(tmp_path)
+    )
+    apply_hydration_plan(plan)
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    out_edges = index_json["references"]["out"]
+    assert len(out_edges) == 1
+    edge = out_edges[0]
+    assert edge["form"] == "recognized"
+    assert edge["detected_via"] == "frontmatter-tag"
+    assert edge["payload"] == "copy"
+    assert edge["context_path"] == "refs/ref-note.md"
+    # the payload is the authored note itself, hydrated like any other file
+    assert (context_dir / "refs" / "ref-note.md").exists()
+    assert (context_dir / "refs" / "plain.md").exists()
+
+
+def test_hydrate_recognizes_manifest_reference_via_fenced_block_without_tag(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / "untagged.md").write_text(
+        """# just a heading, no ctx/manifest tag
+
+```yaml
+components:
+  - name: main
+    text: hello
+```
+""",
+        encoding="utf-8",
+    )
+
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  - name: refs
+    files:
+      - untagged.md
+""",
+        encoding="utf-8",
+    )
+
+    plan = build_hydration_plan(
+        str(manifest_path), overrides=HydrateOverrides(), cwd=str(tmp_path)
+    )
+    apply_hydration_plan(plan)
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    edge = index_json["references"]["out"][0]
+    assert edge["detected_via"] == "fenced-block"
+
+
+def test_hydrate_recognizes_manifest_reference_via_registry_membership(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    from contextualize.manifest import contexts as contexts_module
+
+    registered_note = tmp_path / "registered.md"
+    registered_note.write_text("plain prose, no fenced block or tag", encoding="utf-8")
+
+    class _FakeEntry:
+        def __init__(self, source: Path) -> None:
+            self.manifest = {"source": str(source)}
+            self.target_dir = tmp_path
+
+    monkeypatch.setattr(
+        contexts_module,
+        "load_context_registry",
+        lambda *args, **kwargs: {"registered": _FakeEntry(registered_note)},
+    )
+
+    manifest_path = tmp_path / "manifest.yaml"
+    context_dir = tmp_path / "ctx"
+    manifest_path.write_text(
+        f"""config:
+  context:
+    dir: {context_dir}
+    include-meta: true
+    path-strategy: by-component
+
+components:
+  - name: refs
+    files:
+      - registered.md
+""",
+        encoding="utf-8",
+    )
+
+    plan = build_hydration_plan(
+        str(manifest_path), overrides=HydrateOverrides(), cwd=str(tmp_path)
+    )
+    apply_hydration_plan(plan)
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    edge = index_json["references"]["out"][0]
+    assert edge["detected_via"] == "registry"
+
+
+def test_hydrate_records_full_inclusion_edge_as_pointer(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _isolate_manifest_link_cache(monkeypatch, tmp_path)
+    sub_manifest = tmp_path / "sub.yaml"
+    _write_sub_manifest(sub_manifest)
+
+    context_dir = tmp_path / "ctx"
+    plan = build_hydration_plan_data(
+        {
+            "config": {
+                "context": {
+                    "dir": str(context_dir),
+                    "include-meta": True,
+                    "path-strategy": "on-disk",
+                }
+            },
+            "components": [{"name": "contexts", "manifests": [str(sub_manifest)]}],
+        },
+        manifest_cwd=str(tmp_path),
+        overrides=HydrateOverrides(),
+        cwd=str(tmp_path),
+    )
+    apply_hydration_plan(plan)
+
+    index_json = json.loads((context_dir / "index.json").read_text(encoding="utf-8"))
+    edge = index_json["references"]["out"][0]
+    assert edge["form"] == "full"
+    assert edge["detected_via"] == "manifests-key"
+    assert edge["payload"] == "pointer"
+    assert edge["target_path"] == str(sub_manifest.resolve())
+
+
 def test_hydrate_data_manifest_omits_manifest_source(tmp_path: Path) -> None:
     context_dir = tmp_path / "ctx"
     plan = build_hydration_plan_data(

From c394eb87ec9585485e5ff436dbe67cfb1a4cc0ad Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:42:14 -0400
Subject: [PATCH 4/6] fix(manifest): handle zero-indent YAML block sequences in
 source parsing

YAML permits a list to sit at the same indentation as its parent key
(`key:\n- item`), a style used throughout the real note corpus. The
block-end scan for `components:`/`files:`/`repos:`/`manifests:` keys
was stopping on the first such item instead of the next sibling key,
producing an empty outline (and, for the same reason, an empty group
slice) for any manifest written this way.

Item-boundary scans (finding where one component/member ends and its
sibling begins) are unaffected and still terminate on a same-indent
dash -- only key-block-end scans (finding where a key's value block
ends) now tolerate a same-indent dash as a continuation. Verified
against the real note corpus: outline/normalize_components component
counts matched on all 95 parseable manifests (0 mismatches, down
from 53 before this fix).
---
 src/contextualize/manifest/source.py | 30 ++++++++++++++++++--
 tests/test_manifest_source.py        | 41 +++++++++++++++++++++++++++-
 2 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/src/contextualize/manifest/source.py b/src/contextualize/manifest/source.py
index 6a7a63a..96357fa 100644
--- a/src/contextualize/manifest/source.py
+++ b/src/contextualize/manifest/source.py
@@ -247,7 +247,7 @@ def _find_components_range(
         indent = len(match.group("indent"))
         if max_indent is not None and indent > max_indent:
             continue
-        return index + 1, _find_block_end(lines, index + 1, end, indent)
+        return index + 1, _find_key_block_end(lines, index + 1, end, indent)
     return None
 
 
@@ -333,6 +333,32 @@ def _find_block_end(
     return end
 
 
+def _find_key_block_end(
+    lines: list[str],
+    start: int,
+    end: int,
+    key_indent: int,
+) -> int:
+    """Find where a `key:` mapping's value block ends.
+
+    YAML permits a block sequence to sit at the same indentation as its
+    parent key (`key:\\n- item`), so unlike `_find_block_end` (an item
+    terminator, where a same-indent dash is a sibling), a same-indent dash
+    line here still belongs to this key's value.
+    """
+    for index in range(start, end):
+        line = lines[index]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if indent < key_indent:
+            return index
+        if indent == key_indent and not stripped.startswith("-"):
+            return index
+    return end
+
+
 # --- authored outline: order, comments, disabled members (§3.1, §3.2) ---
 
 
@@ -650,7 +676,7 @@ def _find_named_list_range(
         list_indent = len(match.group("indent"))
         if list_indent <= parent_indent:
             continue
-        return index + 1, _find_block_end(lines, index + 1, end, list_indent)
+        return index + 1, _find_key_block_end(lines, index + 1, end, list_indent)
     return None
 
 
diff --git a/tests/test_manifest_source.py b/tests/test_manifest_source.py
index 3f4b751..edabaac 100644
--- a/tests/test_manifest_source.py
+++ b/tests/test_manifest_source.py
@@ -6,7 +6,12 @@
 import pytest
 
 from contextualize.manifest import source as manifest_source
-from contextualize.manifest.source import load_manifest_source, load_manifest_text
+from contextualize.manifest.manifest import normalize_components
+from contextualize.manifest.source import (
+    iter_active_leaves,
+    load_manifest_source,
+    load_manifest_text,
+)
 
 
 def test_load_manifest_source_extracts_yaml_block_from_text_file(
@@ -137,3 +142,37 @@ def run(args, **kwargs):
 
     assert source.manifest_cwd == str(tmp_path)
     assert source.data["components"] == [{"name": "main", "text": "hello"}]
+
+
+def test_outline_handles_zero_indent_block_sequences(tmp_path: Path) -> None:
+    # YAML permits list items at the same indentation as their parent key;
+    # this style is common in the wild and previously produced an empty
+    # outline (the "components:"/"files:" block-end scan stopped on the
+    # first item instead of the next sibling key).
+    path = tmp_path / "manifest.yaml"
+    path.write_text(
+        """config:
+  root: '~'
+components:
+- name: percept span and facets
+  files:
+  - dev/mood-board/packages/percept/src/percept/span.py
+  - dev/mood-board/packages/percept/src/percept/contracts.py
+- name: current ad-hoc extraction to replace
+  files:
+  - dev/mood-board/src/mood_board/core/director/orchestrator.py
+""",
+        encoding="utf-8",
+    )
+
+    source = load_manifest_source(path)
+    assert source.source_format is not None
+
+    normalized = normalize_components(source.data["components"])
+    leaves = list(iter_active_leaves(source.source_format.outline))
+    assert len(leaves) == len(normalized) == 2
+    assert [leaf["name"] for leaf in leaves] == [
+        "percept span and facets",
+        "current ad-hoc extraction to replace",
+    ]
+    assert [len(leaf["members"]["files"]) for leaf in leaves] == [2, 1]

From 57d896aeb76e8779b508bdec0ceb175dabf72038 Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:44:52 -0400
Subject: [PATCH 5/6] fix(manifest): find member lists on a bare component's
 own dash line

A component with no name/group/set key (`- files:\n  - a.md`) puts
the `files:` key directly on the item's dash line rather than on its
own line; the member-list scan only looked from the line after the
dash onward and silently found no members for such components.
---
 src/contextualize/manifest/source.py | 18 +++++++++++++++++-
 tests/test_manifest_source.py        | 25 +++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/contextualize/manifest/source.py b/src/contextualize/manifest/source.py
index 96357fa..4ac3cd9 100644
--- a/src/contextualize/manifest/source.py
+++ b/src/contextualize/manifest/source.py
@@ -647,7 +647,9 @@ def _parse_all_member_lists(
 ) -> dict[str, list[dict[str, Any]]]:
     members: dict[str, list[dict[str, Any]]] = {}
     for key in _MEMBER_KEYS:
-        list_range = _find_named_list_range(lines, start + 1, end, key, indent)
+        list_range = _first_line_member_list_range(
+            lines, start, end, key, indent
+        ) or _find_named_list_range(lines, start + 1, end, key, indent)
         if list_range is None:
             continue
         list_start, list_end = list_range
@@ -660,6 +662,20 @@ def _parse_all_member_lists(
     return members
 
 
+def _first_line_member_list_range(
+    lines: list[str],
+    start: int,
+    end: int,
+    key: str,
+    indent: int,
+) -> tuple[int, int] | None:
+    """Handle a bare (unnamed) component whose dash is `- files:` itself."""
+    line = lines[start].rstrip("\n")
+    if not re.match(rf"^ *-\s*{key}\s*:\s*(?:#.*)?$", line):
+        return None
+    return start + 1, _find_key_block_end(lines, start + 1, end, indent)
+
+
 def _find_named_list_range(
     lines: list[str],
     start: int,
diff --git a/tests/test_manifest_source.py b/tests/test_manifest_source.py
index edabaac..6d1524c 100644
--- a/tests/test_manifest_source.py
+++ b/tests/test_manifest_source.py
@@ -176,3 +176,28 @@ def test_outline_handles_zero_indent_block_sequences(tmp_path: Path) -> None:
         "current ad-hoc extraction to replace",
     ]
     assert [len(leaf["members"]["files"]) for leaf in leaves] == [2, 1]
+
+
+def test_outline_finds_members_on_bare_unnamed_component(tmp_path: Path) -> None:
+    # `- files:` with no `name:`/`group:`/`set:` key puts the member list key
+    # directly on the item's dash line rather than on its own line.
+    path = tmp_path / "manifest.yaml"
+    path.write_text(
+        """components:
+  - files:
+      - a.md
+      - b.md
+  - name: named
+    files:
+      - c.md
+""",
+        encoding="utf-8",
+    )
+
+    source = load_manifest_source(path)
+    assert source.source_format is not None
+    leaves = list(iter_active_leaves(source.source_format.outline))
+    assert leaves[0]["name"] is None
+    assert len(leaves[0]["members"]["files"]) == 2
+    assert leaves[1]["name"] == "named"
+    assert len(leaves[1]["members"]["files"]) == 1

From 782aae6530be2b99e753aadfe22c5e90499f0c44 Mon Sep 17 00:00:00 2001
From: jmpaz <30947643+jmpaz@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:52:03 -0400
Subject: [PATCH 6/6] fix(hydrate): true up set-fusion tuple annotation

---
 src/contextualize/manifest/hydrate.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/contextualize/manifest/hydrate.py b/src/contextualize/manifest/hydrate.py
index 77815dc..c937f8a 100644
--- a/src/contextualize/manifest/hydrate.py
+++ b/src/contextualize/manifest/hydrate.py
@@ -2588,6 +2588,7 @@ def _build_set_fusion(
             str | None,
             dict[str, Any],
             str | None,
+            bool,
         ]
     ],
     outline_node: dict[str, Any] | None = None,
