spawn-cli 0.1.8__tar.gz → 0.1.10__tar.gz

{spawn_cli-0.1.8/src/spawn_cli.egg-info → spawn_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.8
+Version: 0.1.10
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -27,7 +27,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
 
-On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other. Optional `hints` add short reminders to rendered skills and the Spawn-managed entry block.
 
 **Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
 
@@ -189,7 +189,7 @@ Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guid
 
 **Minimal mental model:**
 
-- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, optional `hints`, etc.
 - `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
 - `**spawn extension check . --strict**` — validate before publishing or tagging a release.
 

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/README.md

@@ -10,7 +10,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
 
-On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other. Optional `hints` add short reminders to rendered skills and the Spawn-managed entry block.
 
 **Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
 
@@ -172,7 +172,7 @@ Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guid
 
 **Minimal mental model:**
 
-- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, optional `hints`, etc.
 - `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
 - `**spawn extension check . --strict**` — validate before publishing or tagging a release.
 

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spawn-cli"
-version = "0.1.8"
+version = "0.1.10"
 description = "A minimal installable Python CLI package."
 readme = "README.md"
 requires-python = ">=3.10"

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/cli.py

@@ -44,8 +44,8 @@ def build_parser() -> argparse.ArgumentParser:
         "refresh",
         help="Sync core config from defaults and rebuild IDE renders",
         description=(
-            "Merge bundled defaults into spawn/.core/config.yaml, then refresh skills, MCP, "
-            "agent ignore, navigation, gitignore metadata, and IDE entry points."
+            "Replace spawn/.core/config.yaml with bundled default core config, then refresh "
+            "skills, MCP, agent ignore, navigation, gitignore metadata, and IDE entry points."
         ),
     )
 

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/core/high_level.py

@@ -63,12 +63,9 @@ def _extend_dir(target_root: Path, extension: str) -> Path:
 
 
 def _agent_ignore_merge_excluding(target_root: Path, skip_ext: str) -> list[str]:
+    """Merged extension ``agent-ignore`` only, omitting *skip_ext*."""
     merged: list[str] = []
     seen: set[str] = set()
-    for g in ll.get_core_agent_ignore(target_root):
-        if g not in seen:
-            seen.add(g)
-            merged.append(g)
     for ext in ll.list_extensions(target_root):
         if ext == skip_ext:
             continue
@@ -79,6 +76,48 @@ def _agent_ignore_merge_excluding(target_root: Path, skip_ext: str) -> list[str]
     return merged
 
 
+def _sync_project_agent_ignore_permissions(target_root: Path, ide: str) -> None:
+    old = ll.get_agent_ignore_list(target_root, ide)
+    new = ll.get_all_agent_ignore(target_root)
+    adapter = ide_get(ide)
+    to_remove = sorted(set(old) - set(new))
+    to_add = sorted(set(new) - set(old))
+    if to_remove:
+        adapter.remove_agent_ignore(target_root, to_remove)
+    if to_add:
+        adapter.add_agent_ignore(target_root, to_add)
+    ll.save_agent_ignore_list(target_root, ide, new)
+
+
+def refresh_core_agent_ignore(target_root: Path, ide: str) -> None:
+    _require_init(target_root)
+    adapter = ide_get(ide)
+    cap = adapter.detect(target_root).capabilities.agent_ignore
+    core = ll.get_core_agent_ignore(target_root)
+    if cap == "native":
+        adapter.rewrite_core_agent_ignore(target_root, core)
+    elif cap == "project":
+        _sync_project_agent_ignore_permissions(target_root, ide)
+
+
+def refresh_extension_agent_ignore(target_root: Path, ide: str) -> None:
+    _require_init(target_root)
+    adapter = ide_get(ide)
+    cap = adapter.detect(target_root).capabilities.agent_ignore
+    ext = ll.get_merged_extension_agent_ignore(target_root)
+    if cap == "native":
+        adapter.rewrite_extension_agent_ignore(target_root, ext)
+        ll.save_agent_ignore_list(target_root, ide, ext)
+    elif cap == "project":
+        _sync_project_agent_ignore_permissions(target_root, ide)
+
+
+def refresh_agent_ignore(target_root: Path, ide: str) -> None:
+    _require_init(target_root)
+    refresh_core_agent_ignore(target_root, ide)
+    refresh_extension_agent_ignore(target_root, ide)
+
+
 def refresh_gitignore(target_root: Path) -> None:
     _require_init(target_root)
     new_items: list[str] = []
@@ -95,16 +134,6 @@ def refresh_gitignore(target_root: Path) -> None:
     ll.remove_from_global_gitignore(target_root, sorted(ex_set - new_set))
 
 
-def refresh_agent_ignore(target_root: Path, ide: str) -> None:
-    _require_init(target_root)
-    old = ll.get_agent_ignore_list(target_root, ide)
-    new = ll.get_all_agent_ignore(target_root)
-    adapter = ide_get(ide)
-    adapter.remove_agent_ignore(target_root, sorted(set(old) - set(new)))
-    adapter.add_agent_ignore(target_root, sorted(set(new) - set(old)))
-    ll.save_agent_ignore_list(target_root, ide, new)
-
-
 def refresh_skills(target_root: Path, ide: str, extension: str) -> None:
     _require_init(target_root)
     adapter = ide_get(ide)
@@ -169,7 +198,17 @@ def remove_mcp(target_root: Path, ide: str, extension: str) -> None:
 
 def refresh_entry_point(target_root: Path, ide: str) -> None:
     _require_init(target_root)
-    ide_get(ide).rewrite_entry_point(target_root, SPAWN_ENTRY_POINT_PROMPT)
+    rollup = ll.rollup_hints_for_agents(target_root)
+    ll.warn_if_agents_hints_exceed_measurement(rollup)
+    if rollup:
+        prompt = (
+            f"{SPAWN_ENTRY_POINT_PROMPT}\nHints:\n"
+            + "\n".join(f"- {h}" for h in rollup)
+            + "\n"
+        )
+    else:
+        prompt = SPAWN_ENTRY_POINT_PROMPT
+    ide_get(ide).rewrite_entry_point(target_root, prompt)
 
 
 def refresh_extension_for_ide(target_root: Path, ide: str, extension: str) -> None:
@@ -192,17 +231,30 @@ def refresh_extension_for_ide(target_root: Path, ide: str, extension: str) -> No
     refresh_mcp(target_root, ide, extension)
     _refresh_skills_all_extensions_for_ide(target_root, ide)
     refresh_agent_ignore(target_root, ide)
+    refresh_navigation(target_root)
 
 
 def remove_extension_for_ide(target_root: Path, ide: str, extension: str) -> None:
     remove_mcp(target_root, ide, extension)
     remove_skills(target_root, ide, extension)
-    old = ll.get_agent_ignore_list(target_root, ide)
-    new = _agent_ignore_merge_excluding(target_root, extension)
+    new_ext = _agent_ignore_merge_excluding(target_root, extension)
     adapter = ide_get(ide)
-    adapter.remove_agent_ignore(target_root, sorted(set(old) - set(new)))
-    adapter.add_agent_ignore(target_root, sorted(set(new) - set(old)))
-    ll.save_agent_ignore_list(target_root, ide, new)
+    cap = adapter.detect(target_root).capabilities.agent_ignore
+    if cap == "native":
+        adapter.rewrite_extension_agent_ignore(target_root, new_ext)
+        ll.save_agent_ignore_list(target_root, ide, new_ext)
+    elif cap == "project":
+        desired = ll.merge_core_and_extension_agent_ignore(
+            ll.get_core_agent_ignore(target_root), new_ext
+        )
+        old = ll.get_agent_ignore_list(target_root, ide)
+        to_remove = sorted(set(old) - set(desired))
+        to_add = sorted(set(desired) - set(old))
+        if to_remove:
+            adapter.remove_agent_ignore(target_root, to_remove)
+        if to_add:
+            adapter.add_agent_ignore(target_root, to_add)
+        ll.save_agent_ignore_list(target_root, ide, desired)
 
 
 def refresh_navigation(target_root: Path) -> None:
@@ -223,9 +275,9 @@ def refresh_rules_navigation(target_root: Path) -> None:
 
 
 def refresh_repository(target_root: Path) -> None:
-    """Sync core config from package defaults and rebuild all IDE-facing metadata."""
+    """Overwrite core config from bundled defaults, then rebuild all IDE-facing metadata."""
     _require_init(target_root)
-    ll.merge_core_config_from_defaults(target_root)
+    ll.sync_core_config_from_defaults(target_root)
     needs_skill = _any_extension_has_skill_files(target_root)
     needs_mcp = _any_extension_has_mcp_servers(target_root)
     for ide in ll.list_ides(target_root):
@@ -535,8 +587,7 @@ def remove_ide(target_root: Path, ide: str) -> None:
     for ext in ll.list_extensions(target_root):
         remove_mcp(target_root, ide, ext)
         remove_skills(target_root, ide, ext)
-    old = ll.get_agent_ignore_list(target_root, ide)
-    ide_get(ide).remove_agent_ignore(target_root, old)
+    ide_get(ide).clear_spawn_agent_ignore(target_root)
     ide_get(ide).finalize_repo_after_ide_removed(target_root)
     ll.remove_ide_from_list(target_root, ide)
     ll.remove_ide_metadata_dir(target_root, ide)
@@ -560,6 +611,8 @@ __all__ = [
     "extension_init",
     "install_extension",
     "refresh_agent_ignore",
+    "refresh_core_agent_ignore",
+    "refresh_extension_agent_ignore",
     "refresh_entry_point",
     "refresh_extension",
     "refresh_extension_for_ide",

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/core/low_level.py

@@ -130,6 +130,182 @@ def _load_ext_config(target_root: Path, extension: str) -> ExtensionConfig:
     return ExtensionConfig.model_validate(raw)
 
 
+_EXTENSION_NAV_HINT_MAX_CODEPOINTS = 512
+_SKILL_HINT_SECTION_COMBINED_MAX_CHARS = 4096
+
+
+def _optional_ext_config(target_root: Path, extension: str) -> ExtensionConfig | None:
+    path = _config_path(target_root, extension)
+    if not path.is_file():
+        return None
+    raw = load_yaml(path)
+    if not raw:
+        return None
+    return ExtensionConfig.model_validate(raw)
+
+
+def _normalized_extension_global_hints_for_navigation(cfg: ExtensionConfig) -> list[str]:
+    """Strip, drop empties, dedupe (first wins), warn + truncate to codepoint limit for persisted navigation."""
+
+    raw_list: list[str] = []
+    if cfg.hints is not None:
+        raw_list.extend(cfg.hints.global_)
+    seen: set[str] = set()
+    out: list[str] = []
+    for h in raw_list:
+        s = h.strip()
+        if not s:
+            continue
+        if s in seen:
+            continue
+        seen.add(s)
+        if len(s) > _EXTENSION_NAV_HINT_MAX_CODEPOINTS:
+            warnings.warn(
+                "Extension navigation hint exceeds 512 Unicode code points and was truncated.",
+                SpawnWarning,
+            )
+            s = s[:_EXTENSION_NAV_HINT_MAX_CODEPOINTS]
+        out.append(s)
+    return out
+
+
+def _truncate_hint_codepoints(text: str, max_codepoints: int) -> tuple[str, bool]:
+    if len(text) <= max_codepoints:
+        return text, False
+    return text[:max_codepoints], True
+
+
+def _merge_hint_streams_ordered(streams: list[list[str]]) -> list[str]:
+    """Dedupe stripped strings with first occurrence winning; earlier streams dominate later ones."""
+
+    seen: set[str] = set()
+    out: list[str] = []
+    for stream in streams:
+        for h in stream:
+            s = h.strip()
+            if not s or s in seen:
+                continue
+            seen.add(s)
+            out.append(s)
+    return out
+
+
+def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]:
+    """Plain-text hints from maintainer-authored read-required ``rules`` rows only (YAML order).
+
+    Hint fields on ``read-contextual`` rules are ignored here.
+    """
+    path = _spawn(target_root) / "navigation.yaml"
+    raw = load_yaml(path)
+    if not isinstance(raw, dict):
+        return []
+    rr = raw.get("read-required")
+    if not isinstance(rr, list):
+        return []
+    out: list[str] = []
+    for grp in rr:
+        if not isinstance(grp, dict):
+            continue
+        rules_raw = grp.get("rules")
+        if not isinstance(rules_raw, list):
+            continue
+        for entry in rules_raw:
+            if not isinstance(entry, dict):
+                continue
+            hint_val = entry.get("hint")
+            if isinstance(hint_val, str):
+                out.append(hint_val)
+    return out
+
+
+def _finalize_hints_for_skill_metadata(merged_hints: list[str]) -> list[str]:
+    """512 codepoints per hint + 4096 char ``Hints:`` section (terminal ``- ...`` when clipped)."""
+
+    trimmed: list[str] = []
+    for h in merged_hints:
+        t, clipped = _truncate_hint_codepoints(h, _EXTENSION_NAV_HINT_MAX_CODEPOINTS)
+        if clipped:
+            warnings.warn(
+                "Skill hint exceeds 512 Unicode code points and was truncated for skill metadata.",
+                SpawnWarning,
+            )
+        trimmed.append(t)
+
+    header = "Hints:\n"
+    warn_combined = (
+        "Skill hints truncated to fit combined 4096 character budget for the Hints section; "
+        "shorten hints and/or split skills."
+    )
+
+    def build_block(strings: list[str], with_ellipsis: bool) -> str:
+        lines = [f"- {s}" for s in strings]
+        if with_ellipsis:
+            lines.append("- ...")
+        if not lines:
+            return ""
+        return header + "\n".join(lines)
+
+    fitted: list[str] = []
+    need_ellipsis = False
+
+    for s in trimmed:
+        plain = build_block(fitted + [s], False)
+        if len(plain) <= _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+            fitted.append(s)
+            continue
+        with_el = build_block(fitted + [s], True)
+        if len(with_el) <= _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+            fitted.append(s)
+            need_ellipsis = True
+            warnings.warn(warn_combined, SpawnWarning)
+            break
+        need_ellipsis = True
+        warnings.warn(warn_combined, SpawnWarning)
+        break
+
+    if need_ellipsis:
+        fitted.append("...")
+    return fitted
+
+
+def _extension_global_hint_streams_ordered(target_root: Path) -> list[list[str]]:
+    """One hint list per extension, in ``list_extensions`` order (sorted ext ids)."""
+
+    streams: list[list[str]] = []
+    for ext in list_extensions(target_root):
+        cfg = _load_ext_config(target_root, ext)
+        streams.append(list(cfg.hints.global_) if cfg.hints else [])
+    return streams
+
+
+def rollup_hints_for_agents(target_root: Path) -> list[str]:
+    """Deduped ordered hints for ``AGENTS.md``: every extension ``hints.global``, then maintainer."""
+
+    streams = _extension_global_hint_streams_ordered(target_root)
+    streams.append(_navigation_read_required_rule_hints_ordered(target_root))
+    return _merge_hint_streams_ordered(streams)
+
+
+def warn_if_agents_hints_exceed_measurement(hints: list[str]) -> None:
+    """Warn when thresholds are exceeded without mutating hints (full text still written)."""
+
+    if any(len(h) > _EXTENSION_NAV_HINT_MAX_CODEPOINTS for h in hints):
+        warnings.warn(
+            "AGENTS.md hints contain at least one hint over 512 Unicode code points "
+            "(full text retained); shorten hints and/or reduce installed extensions.",
+            SpawnWarning,
+        )
+    block = ""
+    if hints:
+        block = "Hints:\n" + "\n".join(f"- {h}" for h in hints)
+    if hints and len(block) > _SKILL_HINT_SECTION_COMBINED_MAX_CHARS:
+        warnings.warn(
+            "AGENTS.md hints exceed combined 4096 character measurement "
+            "(full text retained); shorten hints and/or reduce installed extensions.",
+            SpawnWarning,
+        )
+
+
 def _file_refs_for_global(extension: ExtensionConfig, flag_required: bool) -> list[SkillFileRef]:
     out: list[SkillFileRef] = []
     for path_str, ent in extension.files.items():
@@ -353,6 +529,16 @@ def _required_read_description_for_path(
 
 def generate_skills_metadata(target_root: Path, extension: str) -> list[SkillMetadata]:
     cfg_ext = _load_ext_config(target_root, extension)
+    maintainer_hints = _navigation_read_required_rule_hints_ordered(target_root)
+    global_streams = _extension_global_hint_streams_ordered(target_root)
+    local_raw = list(cfg_ext.hints.local) if cfg_ext.hints else []
+    merged_for_skill = _merge_hint_streams_ordered(
+        [*global_streams, local_raw, maintainer_hints]
+    )
+    skill_hints = (
+        _finalize_hints_for_skill_metadata(merged_for_skill) if merged_for_skill else []
+    )
+
     merged_global_required = _flatten_global_refs_ordered(
         target_root, get_required_read_global_all(target_root)
     )
@@ -422,6 +608,7 @@ def generate_skills_metadata(target_root: Path, extension: str) -> list[SkillMet
                 name=raw.name,
                 description=raw.description,
                 content=raw.content,
+                hints=list(skill_hints),
                 required_read=required_out,
                 auto_read=auto_out,
             )
@@ -519,12 +706,11 @@ def get_core_agent_ignore(target_root: Path) -> list[str]:
     return list(core.agent_ignore)
 
 
-def merge_core_config_from_defaults(target_root: Path) -> None:
-    """Merge bundled default core config into ``spawn/.core/config.yaml``.
+def sync_core_config_from_defaults(target_root: Path) -> None:
+    """Overwrite ``spawn/.core/config.yaml`` with bundled default ``CoreConfig``.
 
-    ``version`` becomes the bundled default. ``agent-ignore`` is the bundled
-    list (in resource order) followed by any existing patterns not present in
-    the default set.
+    Validates that an existing repo file parses as ``CoreConfig`` before
+    replacing it so corrupted files are not silently clobbered.
     """
     path = _spawn(target_root) / ".core" / "config.yaml"
     if not path.is_file():
@@ -548,16 +734,10 @@ def merge_core_config_from_defaults(target_root: Path) -> None:
             "spawn/.core/config.yaml is empty or invalid; restore it or run spawn init again."
         )
     try:
-        current = CoreConfig.model_validate(raw_existing)
+        CoreConfig.model_validate(raw_existing)
     except Exception as e:
         raise SpawnError(f"invalid spawn/.core/config.yaml: {e}") from e
-    default_set = set(default_core.agent_ignore)
-    merged_ignore = list(default_core.agent_ignore)
-    for g in current.agent_ignore:
-        if g not in default_set:
-            merged_ignore.append(g)
-    out = CoreConfig(version=default_core.version, agent_ignore=merged_ignore)
-    save_yaml(path, out.model_dump(by_alias=True))
+    save_yaml(path, default_core.model_dump(by_alias=True))
 
 
 def get_ext_agent_ignore(target_root: Path, extension: str) -> list[str]:
@@ -566,12 +746,16 @@ def get_ext_agent_ignore(target_root: Path, extension: str) -> list[str]:
 
 
 def get_all_agent_ignore(target_root: Path) -> list[str]:
+    return merge_core_and_extension_agent_ignore(
+        get_core_agent_ignore(target_root),
+        get_merged_extension_agent_ignore(target_root),
+    )
+
+
+def get_merged_extension_agent_ignore(target_root: Path) -> list[str]:
+    """Stable deduped merge of ``agent-ignore`` from all installed extensions."""
     merged: list[str] = []
     seen: set[str] = set()
-    for g in get_core_agent_ignore(target_root):
-        if g not in seen:
-            seen.add(g)
-            merged.append(g)
     for ext in list_extensions(target_root):
         for g in get_ext_agent_ignore(target_root, ext):
             if g not in seen:
@@ -580,6 +764,20 @@ def get_all_agent_ignore(target_root: Path) -> list[str]:
     return merged
 
 
+def merge_core_and_extension_agent_ignore(core: list[str], ext: list[str]) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for g in core:
+        if g not in seen:
+            seen.add(g)
+            merged.append(g)
+    for g in ext:
+        if g not in seen:
+            seen.add(g)
+            merged.append(g)
+    return merged
+
+
 def get_ext_git_ignore(target_root: Path, extension: str) -> list[str]:
     cfg = _load_ext_config(target_root, extension)
     return list(cfg.git_ignore)
@@ -671,6 +869,13 @@ def _agent_ignore_list_path(target_root: Path, ide: str) -> Path:
 
 
 def get_agent_ignore_list(target_root: Path, ide: str) -> list[str]:
+    """Last persisted ignore snapshot for *ide*.
+
+    Native file-based ignores: extension ``agent-ignore`` merge only.
+
+    Project-style ignores (e.g. Claude Code): full core+extension merge used for
+    JSON permissions diffing.
+    """
     lines = read_lines(_agent_ignore_list_path(target_root, ide))
     return [ln for ln in lines if ln.strip() and not ln.lstrip().startswith("#")]
 
@@ -839,7 +1044,13 @@ def save_extension_navigation(
     _strip_ext_sections_inplace(rr, extension)
     _strip_ext_sections_inplace(rc, extension)
     if read_required_files:
-        rr.append({"ext": extension, "files": _nav_refs_to_files(read_required_files)})
+        block: dict[str, Any] = {"ext": extension, "files": _nav_refs_to_files(read_required_files)}
+        cfg_opt = _optional_ext_config(target_root, extension)
+        if cfg_opt is not None:
+            hints_nav = _normalized_extension_global_hints_for_navigation(cfg_opt)
+            if hints_nav:
+                block["hints"] = hints_nav
+        rr.append(block)
     if read_contextual_files:
         req_norm = {_norm_read_path(r.file) for r in read_required_files}
         contextual_only = [
@@ -913,7 +1124,14 @@ def save_rules_navigation(target_root: Path) -> None:
             rk = posix_norm(str(entry['path']))
             exists = rk in paths_on_disk and (Path(target_root) / Path(rk)).is_file()
             if exists:
-                out.append({'path': rk, 'description': str(entry.get('description') or 'Local rule file.')})
+                row: dict[str, Any] = {
+                    'path': rk,
+                    'description': str(entry.get('description') or 'Local rule file.'),
+                }
+                hint_val = entry.get('hint')
+                if isinstance(hint_val, str):
+                    row['hint'] = hint_val
+                out.append(row)
             else:
                 warnings.warn(
                     f"Removed missing rule path from navigation: {rk}",
@@ -977,6 +1195,7 @@ __all__ = [
     "get_folders",
     "get_git_ignore_list",
     "get_global_gitignore",
+    "get_merged_extension_agent_ignore",
     "get_navigation_metadata",
     "get_rendered_mcp",
     "get_rendered_skills",
@@ -990,7 +1209,8 @@ __all__ = [
     "list_ides",
     "list_mcp",
     "list_skills",
-    "merge_core_config_from_defaults",
+    "sync_core_config_from_defaults",
+    "merge_core_and_extension_agent_ignore",
     "METADATA_TEMP_MAX_AGE_SECONDS",
     "normalize_skill_name",
     "prune_metadata_temp",
@@ -998,6 +1218,7 @@ __all__ = [
     "remove_from_global_gitignore",
     "remove_ide_metadata_dir",
     "remove_ide_from_list",
+    "rollup_hints_for_agents",
     "save_agent_ignore_list",
     "save_extension_navigation",
     "save_git_ignore_list",
@@ -1006,5 +1227,6 @@ __all__ = [
     "save_skills_rendered",
     "supported_ide_keys",
     "validate_rendered_identity",
+    "warn_if_agents_hints_exceed_measurement",
 ]
 

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/__init__.py

@@ -17,6 +17,10 @@ from .github_copilot import GitHubCopilotAdapter
 from .windsurf import WindsurfAdapter
 from .registry import (
     ALIASES,
+    CORE_IGNORE_BLOCK_END,
+    CORE_IGNORE_BLOCK_START,
+    EXT_IGNORE_BLOCK_END,
+    EXT_IGNORE_BLOCK_START,
     IGNORE_BLOCK_END,
     IGNORE_BLOCK_START,
     SPAWN_BLOCK_END,
@@ -43,6 +47,10 @@ __all__ = [
     "GeminiCliAdapter",
     "GitHubCopilotAdapter",
     "DetectResult",
+    "CORE_IGNORE_BLOCK_END",
+    "CORE_IGNORE_BLOCK_START",
+    "EXT_IGNORE_BLOCK_END",
+    "EXT_IGNORE_BLOCK_START",
     "IGNORE_BLOCK_END",
     "IGNORE_BLOCK_START",
     "IdeAdapter",

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/_helpers.py

@@ -14,6 +14,12 @@ SPAWN_BLOCK_END = "<!-- spawn:end -->"
 IGNORE_BLOCK_START = "# spawn:start"
 IGNORE_BLOCK_END = "# spawn:end"
 
+# Dual-region agent ignore (core from spawn/.core vs extensions).
+CORE_IGNORE_BLOCK_START = "# spawn:core:start"
+CORE_IGNORE_BLOCK_END = "# spawn:core:end"
+EXT_IGNORE_BLOCK_START = "# spawn:ext:start"
+EXT_IGNORE_BLOCK_END = "# spawn:ext:end"
+
 _NAV_YAML_FILE = "spawn/navigation.yaml"
 _NAV_YAML_DESCRIPTION = "Merged Spawn navigation (read-required, read-contextual)."
 
@@ -36,7 +42,8 @@ def _mandatory_reads_for_render(skill: SkillMetadata) -> list[SkillFileRef]:
 
 def render_skill_md(skill: SkillMetadata) -> str:
     """Render normalized skill to Markdown with frontmatter, skill body,
-    mandatory reads (navigation path last), and contextual reads."""
+    hints (stable order from metadata), mandatory reads (navigation path last),
+    and contextual reads."""
     lines = [
         "---",
         f"name: {skill.name}",
@@ -45,8 +52,13 @@ def render_skill_md(skill: SkillMetadata) -> str:
         "",
         skill.content,
         "",
-        "Mandatory reads:",
     ]
+    if skill.hints:
+        lines += ["Hints:"]
+        for h in skill.hints:
+            lines += [f"- {h}"]
+        lines += [""]
+    lines += ["Mandatory reads:"]
     for ref in _mandatory_reads_for_render(skill):
         lines += [f"- `{ref.file}` - {ref.description}"]
     lines += [""]
@@ -112,6 +124,149 @@ def rewrite_ignore_block(file_path: Path, globs: list[str]) -> None:
     file_path.write_text("".join(new_lines), encoding="utf-8")
 
 
+def _normalize_ignore_inner_lines(inner: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for ln in inner:
+        st = ln.strip()
+        if not st or st.startswith("#"):
+            continue
+        if st not in seen:
+            seen.add(st)
+            out.append(st)
+    return out
+
+
+def _format_optional_block(start: str, end: str, globs: list[str]) -> list[str]:
+    body = [g for g in globs if g.strip()]
+    if not body:
+        return []
+    lines = [start + "\n"] + [g.strip() + "\n" for g in body] + [end + "\n"]
+    return lines
+
+
+def _flatten_chunks(chunks: list[list[str]]) -> list[str]:
+    out: list[str] = []
+    for ch in chunks:
+        out.extend(ch)
+    return out
+
+
+def _rebuild_from_user_chunks(
+    chunks: list[list[str]], core_globs: list[str], ext_globs: list[str]
+) -> list[str]:
+    """Interleave user segments with core and ext blocks (see spawn agent-ignore spec)."""
+    core_b = _format_optional_block(CORE_IGNORE_BLOCK_START, CORE_IGNORE_BLOCK_END, core_globs)
+    ext_b = _format_optional_block(EXT_IGNORE_BLOCK_START, EXT_IGNORE_BLOCK_END, ext_globs)
+    if not core_b and not ext_b:
+        return _flatten_chunks(chunks)
+    if len(chunks) == 0:
+        return core_b + ext_b
+    if len(chunks) == 1:
+        return chunks[0] + core_b + ext_b
+    if len(chunks) == 2:
+        return chunks[0] + core_b + ext_b + chunks[1]
+    out: list[str] = []
+    out += chunks[0] + core_b + chunks[1] + ext_b
+    for c in chunks[2:]:
+        out += c
+    return out
+
+
+def _block_kind(line_stripped: str) -> str | None:
+    if line_stripped == IGNORE_BLOCK_START:
+        return "legacy"
+    if line_stripped == CORE_IGNORE_BLOCK_START:
+        return "core"
+    if line_stripped == EXT_IGNORE_BLOCK_START:
+        return "ext"
+    return None
+
+
+def _end_marker_for(kind: str) -> str:
+    if kind == "legacy":
+        return IGNORE_BLOCK_END
+    if kind == "core":
+        return CORE_IGNORE_BLOCK_END
+    if kind == "ext":
+        return EXT_IGNORE_BLOCK_END
+    raise ValueError(kind)
+
+
+def _parse_split_agent_ignore_lines(
+    raw_lines: list[str],
+) -> tuple[list[list[str]], list[str], list[str]]:
+    """Split file into user chunks (between blocks), core globs, ext globs.
+
+    Legacy ``# spawn:start`` … ``# spawn:end`` inner lines are discarded (migration).
+    Unclosed blocks: inner runs to EOF.
+    """
+    chunks: list[list[str]] = []
+    core: list[str] = []
+    ext: list[str] = []
+    cur: list[str] = []
+    i = 0
+    n = len(raw_lines)
+    while i < n:
+        kind = _block_kind(raw_lines[i].strip())
+        if kind is None:
+            cur.append(raw_lines[i])
+            i += 1
+            continue
+        if cur:
+            chunks.append(cur)
+            cur = []
+        end_marker = _end_marker_for(kind)
+        j = i + 1
+        inner: list[str] = []
+        while j < n and raw_lines[j].strip() != end_marker:
+            inner.append(raw_lines[j])
+            j += 1
+        if kind == "core":
+            core = _normalize_ignore_inner_lines(inner)
+        elif kind == "ext":
+            ext = _normalize_ignore_inner_lines(inner)
+        # legacy: discard inner
+        i = j + 1 if j < n and raw_lines[j].strip() == end_marker else j
+    if cur:
+        chunks.append(cur)
+    return chunks, core, ext
+
+
+def parse_split_agent_ignore_file(file_path: Path) -> tuple[list[list[str]], list[str], list[str]]:
+    if not file_path.exists():
+        return [], [], []
+    raw = file_path.read_text(encoding="utf-8").splitlines(True)
+    return _parse_split_agent_ignore_lines(raw)
+
+
+def write_split_agent_ignore_file(
+    file_path: Path, chunks: list[list[str]], core_globs: list[str], ext_globs: list[str]
+) -> None:
+    body = _rebuild_from_user_chunks(chunks, core_globs, ext_globs)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    if not body:
+        if file_path.exists():
+            file_path.write_text("", encoding="utf-8")
+        return
+    file_path.write_text("".join(body), encoding="utf-8")
+
+
+def rewrite_core_agent_ignore_region(file_path: Path, core_globs: list[str]) -> None:
+    chunks, _, ext = parse_split_agent_ignore_file(file_path)
+    write_split_agent_ignore_file(file_path, chunks, core_globs, ext)
+
+
+def rewrite_extension_agent_ignore_region(file_path: Path, ext_globs: list[str]) -> None:
+    chunks, core, _ = parse_split_agent_ignore_file(file_path)
+    write_split_agent_ignore_file(file_path, chunks, core, ext_globs)
+
+
+def clear_split_agent_ignore_file(file_path: Path) -> None:
+    chunks, _, _ = parse_split_agent_ignore_file(file_path)
+    write_split_agent_ignore_file(file_path, chunks, [], [])
+
+
 def remove_ignore_block(file_path: Path, globs: list[str]) -> None:
     """Remove Spawn-managed ignore lines or the whole managed block.
 
@@ -156,13 +311,22 @@ def remove_ignore_block(file_path: Path, globs: list[str]) -> None:
 
 
 __all__ = [
+    "CORE_IGNORE_BLOCK_END",
+    "CORE_IGNORE_BLOCK_START",
+    "EXT_IGNORE_BLOCK_END",
+    "EXT_IGNORE_BLOCK_START",
     "IGNORE_BLOCK_END",
     "IGNORE_BLOCK_START",
     "SPAWN_BLOCK_END",
     "SPAWN_BLOCK_START",
+    "clear_split_agent_ignore_file",
     "normalize_skill_name",
+    "parse_split_agent_ignore_file",
     "remove_ignore_block",
     "render_skill_md",
+    "rewrite_core_agent_ignore_region",
+    "rewrite_extension_agent_ignore_region",
     "rewrite_ignore_block",
     "rewrite_managed_block",
+    "write_split_agent_ignore_file",
 ]

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/claude_code.py

@@ -6,6 +6,7 @@ import json
 import warnings
 from pathlib import Path
 
+from spawn_cli.core import low_level as ll
 from spawn_cli.ide import _vacancy as _vac
 from spawn_cli.ide.registry import (
     DetectResult,
@@ -126,6 +127,11 @@ class ClaudeCodeAdapter(IdeAdapter):
         perms["deny"] = [g for g in deny if g not in drop]
         settings_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
 
+    def clear_spawn_agent_ignore(self, target_root: Path) -> None:
+        recorded = ll.get_agent_ignore_list(target_root, self.key)
+        if recorded:
+            self.remove_agent_ignore(target_root, recorded)
+
     def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
         ep = target_root / "CLAUDE.md"
         if (target_root / ".claude" / "CLAUDE.md").exists():

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/cursor.py

@@ -7,6 +7,13 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide._helpers import (
+    clear_split_agent_ignore_file,
+    remove_ignore_block,
+    rewrite_core_agent_ignore_region,
+    rewrite_extension_agent_ignore_region,
+    rewrite_ignore_block,
+)
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -15,8 +22,6 @@ from spawn_cli.ide.registry import (
     normalize_skill_name,
     render_skill_md,
     rewrite_managed_block,
-    rewrite_ignore_block,
-    remove_ignore_block,
 )
 from spawn_cli.models.mcp import McpServer, NormalizedMcp
 from spawn_cli.models.skill import SkillMetadata
@@ -108,6 +113,15 @@ class CursorAdapter(IdeAdapter):
     def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
         remove_ignore_block(target_root / ".cursorignore", globs)
 
+    def rewrite_core_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_core_agent_ignore_region(target_root / ".cursorignore", globs)
+
+    def rewrite_extension_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_extension_agent_ignore_region(target_root / ".cursorignore", globs)
+
+    def clear_spawn_agent_ignore(self, target_root: Path) -> None:
+        clear_split_agent_ignore_file(target_root / ".cursorignore")
+
     def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
         ep = target_root / "AGENTS.md"
         rewrite_managed_block(ep, prompt)

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/gemini_cli.py

@@ -7,6 +7,14 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide._helpers import (
+    clear_split_agent_ignore_file,
+    remove_ignore_block,
+    rewrite_core_agent_ignore_region,
+    rewrite_extension_agent_ignore_region,
+    rewrite_ignore_block,
+    rewrite_managed_block,
+)
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -14,9 +22,6 @@ from spawn_cli.ide.registry import (
     register,
     normalize_skill_name,
     render_skill_md,
-    rewrite_managed_block,
-    rewrite_ignore_block,
-    remove_ignore_block,
 )
 from spawn_cli.models.mcp import McpServer, NormalizedMcp
 from spawn_cli.models.skill import SkillMetadata
@@ -111,6 +116,15 @@ class GeminiCliAdapter(IdeAdapter):
     def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
         remove_ignore_block(target_root / ".geminiignore", globs)
 
+    def rewrite_core_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_core_agent_ignore_region(target_root / ".geminiignore", globs)
+
+    def rewrite_extension_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_extension_agent_ignore_region(target_root / ".geminiignore", globs)
+
+    def clear_spawn_agent_ignore(self, target_root: Path) -> None:
+        clear_split_agent_ignore_file(target_root / ".geminiignore")
+
     def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
         ep = target_root / "GEMINI.md"
         rewrite_managed_block(ep, prompt)

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/registry.py

@@ -9,6 +9,10 @@ from pathlib import Path
 from spawn_cli.core.errors import SpawnError
 from spawn_cli.core.low_level import CANONICAL_IDE_KEYS
 from spawn_cli.ide._helpers import (
+    CORE_IGNORE_BLOCK_END,
+    CORE_IGNORE_BLOCK_START,
+    EXT_IGNORE_BLOCK_END,
+    EXT_IGNORE_BLOCK_START,
     IGNORE_BLOCK_END,
     IGNORE_BLOCK_START,
     SPAWN_BLOCK_END,
@@ -74,6 +78,15 @@ class IdeAdapter(ABC):
     @abstractmethod
     def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None: ...
 
+    def rewrite_core_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+
+    def rewrite_extension_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        del target_root, globs
+
+    def clear_spawn_agent_ignore(self, target_root: Path) -> None:
+        del target_root
+
     @abstractmethod
     def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
         """Returns rendered path or warning string."""
@@ -122,7 +135,11 @@ def detect_supported_ides(target_root: Path) -> dict[str, DetectResult]:
 
 __all__ = [
     "ALIASES",
+    "CORE_IGNORE_BLOCK_END",
+    "CORE_IGNORE_BLOCK_START",
     "DetectResult",
+    "EXT_IGNORE_BLOCK_END",
+    "EXT_IGNORE_BLOCK_START",
     "IdeAdapter",
     "IdeCapabilities",
     "IGNORE_BLOCK_END",

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/ide/windsurf.py

@@ -6,6 +6,14 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide._helpers import (
+    clear_split_agent_ignore_file,
+    remove_ignore_block,
+    rewrite_core_agent_ignore_region,
+    rewrite_extension_agent_ignore_region,
+    rewrite_ignore_block,
+    rewrite_managed_block,
+)
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -13,9 +21,6 @@ from spawn_cli.ide.registry import (
     register,
     normalize_skill_name,
     render_skill_md,
-    rewrite_managed_block,
-    rewrite_ignore_block,
-    remove_ignore_block,
 )
 from spawn_cli.models.mcp import NormalizedMcp
 from spawn_cli.models.skill import SkillMetadata
@@ -77,6 +82,15 @@ class WindsurfAdapter(IdeAdapter):
     def remove_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
         remove_ignore_block(target_root / ".codeiumignore", globs)
 
+    def rewrite_core_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_core_agent_ignore_region(target_root / ".codeiumignore", globs)
+
+    def rewrite_extension_agent_ignore(self, target_root: Path, globs: list[str]) -> None:
+        rewrite_extension_agent_ignore_region(target_root / ".codeiumignore", globs)
+
+    def clear_spawn_agent_ignore(self, target_root: Path) -> None:
+        clear_split_agent_ignore_file(target_root / ".codeiumignore")
+
     def rewrite_entry_point(self, target_root: Path, prompt: str) -> str:
         ep = target_root / "AGENTS.md"
         rewrite_managed_block(ep, prompt)

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/models/config.py

@@ -40,6 +40,15 @@ class SkillEntry(BaseModel):
     required_read: list[str] = Field(default_factory=list, alias="required-read")
 
 
+class ExtensionHints(BaseModel):
+    """Optional extension-authored hints (plain strings only)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    global_: list[str] = Field(default_factory=list, alias="global")
+    local: list[str] = Field(default_factory=list)
+
+
 class SetupConfig(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
@@ -62,6 +71,7 @@ class ExtensionConfig(BaseModel):
     git_ignore: list[str] = Field(default_factory=list, alias="git-ignore")
     skills: dict[str, SkillEntry] = Field(default_factory=dict)
     setup: Optional[SetupConfig] = None
+    hints: Optional[ExtensionHints] = None
 
 
 class CoreConfig(BaseModel):

{spawn_cli-0.1.8 → spawn_cli-0.1.10}/src/spawn_cli/models/skill.py

@@ -25,5 +25,6 @@ class SkillMetadata(BaseModel):
     name: str
     description: str
     content: str
+    hints: list[str] = Field(default_factory=list)
     required_read: list[SkillFileRef] = Field(default_factory=list)
     auto_read: list[SkillFileRef] = Field(default_factory=list)

{spawn_cli-0.1.8 → spawn_cli-0.1.10/src/spawn_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.8
+Version: 0.1.10
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -27,7 +27,7 @@ Spawn is a framework for building **AIDD** (AI-driven development) methodologies
 
 Several methodologies in one repo stay aligned because Spawn maintains **one shared navigation index**: [`spawn/navigation.yaml`](spec/design/data-structure.md) aggregates mandatory and contextual reads from **every installed extension** plus local [`spawn/rules/`](spec/design/user-guide.md) (refreshed with `spawn rules refresh`). Agents are steered through that file instead of chasing disconnected README fragments.
 
-On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other.
+On each install or refresh, the CLI **regenerates IDE-facing artifacts** so skills and entry points stay consistent across extensions: rendered skill bodies include **paths and descriptions** wired from navigation (required reads, contextual hints, rule files), MCP snippets normalize server definitions per IDE adapter, and ignore lists merge without manual copy-paste. The net effect is that methodology files, generated skill links, and repo rules **compose** rather than contradict each other. Optional `hints` add short reminders to rendered skills and the Spawn-managed entry block.
 
 **Example:** [**spawn-ext-spectask**](https://github.com/noant/spawn-ext-spectask) (Spec-Tasks methodology: spec layout, skills, design index) and [**spawn-ext-creator**](https://github.com/noant/spawn-ext-creator) (authoring flows, including agent-guided extension bootstrap) can be installed in the **same** repository and still share that single index and merged IDE outputs.
 
@@ -189,7 +189,7 @@ Read **[spec/design/extension-author-guide.md](spec/design/extension-author-guid
 
 **Minimal mental model:**
 
-- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, etc.
+- `**extsrc/config.yaml`** — `schema`, `version`, stable `**name`** (install path `spawn/.extend/<name>/`), plus `files`, `skills`, ignores, optional `hints`, etc.
 - `**extsrc/files/**` — template tree mirrored into the target repo according to `files:` entries.
 - `**spawn extension check . --strict**` — validate before publishing or tagging a release.