claude-code-capabilities 0.1.2__py3-none-any.whl

capdisc/scope/inventory/render.py

@@ -0,0 +1,149 @@
+"""Render a `ScopeInventory` snapshot as plain text or a self-contained HTML page."""
+
+from __future__ import annotations
+
+from ...html import e, pill, preview, redact_home
+from ..types import ScopeKind
+from .assets import INVENTORY_SCRIPT, INVENTORY_STYLE, PREVIEW_CHARS
+from .capture import CapturedArtifact, ScopeInventory
+
+
+def render_inventory(inventory: ScopeInventory) -> str:
+    """Render a snapshot as human-readable text. Pure — returns text, prints nothing.
+
+    Args:
+        inventory: The snapshot to render.
+
+    Returns:
+        A multi-line report: every capture grouped by scope (in precedence order), then the
+        effective set and the hook events in effect.
+    """
+    order = {scope: index for index, scope in enumerate(ScopeKind)}
+    captures = sorted(
+        inventory.artifacts,
+        key=lambda c: (order[c.scope], c.kind.value, c.precedence, c.name),
+    )
+    lines = [f"ScopeInventory — {len(inventory.artifacts)} artifacts"]
+    current_scope: ScopeKind | None = None
+    for capture in captures:
+        if capture.scope is not current_scope:
+            current_scope = capture.scope
+            lines.append(f"\n[{capture.scope.value}]")
+        lines.append(
+            f"  {capture.kind.value:<7} {capture.name:<22} {capture.shareable.value:<13}"
+            f" rank={capture.precedence}  {capture.path}"
+        )
+
+    lines.append("\neffective (what Claude Code uses):")
+    for capture in sorted(inventory.effective, key=lambda c: (c.kind.value, c.name)):
+        lines.append(
+            f"  {capture.kind.value:<7} {capture.name:<22} <- {capture.scope.value}/"
+            f"{capture.shareable.value}"
+        )
+
+    events = sorted({event.value for config in inventory.hook_configs for event in config.root})
+    lines.append(
+        f"\nhook configs: {len(inventory.hook_configs)}  events: {', '.join(events) or '(none)'}"
+    )
+    return "\n".join(lines)
+
+
+def _artifact_card(capture: CapturedArtifact, is_effective: bool) -> str:
+    """One capture rendered as a card: header pills, path, and a content preview.
+
+    Args:
+        capture: The capture to render; every dynamic value is escaped.
+        is_effective: Whether this capture is in the effective set (wins resolution).
+
+    Returns:
+        The card markup, tagged with a lowercased `data-s` search string for the filter.
+    """
+    marker = (
+        pill("effective", "eff-b")
+        if is_effective
+        else f'<span class="id">rank {e(capture.precedence)} (shadowed)</span>'
+    )
+    head = (
+        pill(capture.kind.value, f"k-{capture.kind.value}")
+        + f'<span class="ref">{e(capture.name)}</span>'
+        + pill(f"{capture.scope.value}/{capture.shareable.value}")
+        + marker
+        + pill(capture.resolution.value)
+    )
+    path_line = f'<div class="path">{e(redact_home(capture.path))}</div>'
+    inner = f'<div class="row">{head}</div>{path_line}' + preview(capture.contents[:PREVIEW_CHARS])
+    terms = (capture.name, capture.kind.value, capture.scope.value, redact_home(capture.path))
+    search = e(" ".join(terms).lower())
+    klass = "eff" if is_effective else "shadow"
+    return f'<div class="card {klass}" data-s="{search}">{inner}</div>'
+
+
+def render_inventory_html(inventory: ScopeInventory) -> str:
+    """Render a snapshot as one self-contained HTML document. Pure — returns the markup
+    string, prints nothing, does no I/O.
+
+    All markup is built here in Python and every dynamic value is escaped; the inline
+    script only toggles classes, sets `style.display`, and reads the filter input — it
+    never assigns markup. Inline `<style>` and `<script>` only, no external assets.
+
+    Args:
+        inventory: The snapshot to render.
+
+    Returns:
+        A standalone HTML document: every capture grouped by scope (in precedence order)
+        as a card, then the effective set and the hook events in effect.
+    """
+    effective = set(inventory.effective)
+    order = {scope: index for index, scope in enumerate(ScopeKind)}
+    captures = sorted(
+        inventory.artifacts,
+        key=lambda c: (order[c.scope], c.kind.value, c.precedence, c.name),
+    )
+    cards: list[str] = []
+    current_scope: ScopeKind | None = None
+    for capture in captures:
+        if capture.scope is not current_scope:
+            current_scope = capture.scope
+            cards.append(f'<div class="grp">{e(capture.scope.value)}</div>')
+        cards.append(_artifact_card(capture, capture in effective))
+    captures_html = "".join(cards) or '<div class="empty">nothing captured on disk</div>'
+
+    effective_rows = (
+        "".join(
+            f'<div class="card eff"><div class="row">'
+            f"{pill(c.kind.value, f'k-{c.kind.value}')}"
+            f'<span class="ref">{e(c.name)}</span>'
+            f"{pill(f'{c.scope.value}/{c.shareable.value}')}</div></div>"
+            for c in sorted(inventory.effective, key=lambda c: (c.kind.value, c.name))
+        )
+        or '<div class="empty">nothing effective</div>'
+    )
+
+    events = sorted({event.value for config in inventory.hook_configs for event in config.root})
+    event_bar = (
+        '<div class="eventbar">'
+        + "".join(f'<span class="event">{e(ev)}</span>' for ev in events)
+        + "</div>"
+        if events
+        else '<div class="empty">no hook events in effect</div>'
+    )
+
+    return (
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        "<title>ScopeInventory</title>"
+        f"<style>{INVENTORY_STYLE}</style></head><body>"
+        "<header><h1>ScopeInventory</h1>"
+        f'<div class="meta"><b>{e(len(inventory.artifacts))}</b> artifacts · '
+        f"<b>{e(len(inventory.effective))}</b> effective · "
+        f"<b>{e(len(inventory.hook_configs))}</b> hook configs</div></header>"
+        "<main>"
+        '<input class="search" placeholder="filter captures…">'
+        f'<div class="grp">captures by scope</div>{captures_html}'
+        f'<div class="grp">effective (what Claude Code uses)</div>{effective_rows}'
+        f'<div class="grp">hook events in effect '
+        f"({e(len(inventory.hook_configs))} configs)</div>"
+        f"{event_bar}"
+        "</main>"
+        f"<script>{INVENTORY_SCRIPT}</script></body></html>"
+    )

capdisc/scope/inventory/roots.py

@@ -0,0 +1,175 @@
+"""Root/path discovery: the real `.claude`/managed directories to scan for each scope."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import get_args
+
+from ...base import FrozenModel
+from ..locations import Artifact
+from ..types import ArtifactKind, ScanBasePath, ScopeKind
+
+
+def artifact_kinds() -> list[Artifact]:
+    """One canonical instance of every artifact descriptor, derived from the union, not listed."""
+    return [variant() for variant in get_args(get_args(Artifact)[0])]
+
+
+def _project_bases(start: Path) -> list[Path]:
+    """The project-scope `.claude` directories, walking up from `start` to the repo root.
+
+    How Claude Code finds project scope no matter which subdirectory you launched from.
+
+    Args:
+        start: The directory the search walks up from (resolved first).
+
+    Returns:
+        Each `.claude` from `start` up to and including the repo root, nearest first. With no
+        enclosing repo, just the start dir's own `.claude`, or `[]` if it has none.
+    """
+    start = start.resolve()
+    bases: list[Path] = []
+    for current in (start, *start.parents):
+        claude_dir = current / ".claude"
+        if claude_dir.is_dir():
+            bases.append(claude_dir)
+        if (current / ".git").exists():
+            return bases
+    start_claude = start / ".claude"
+    return [start_claude] if start_claude.is_dir() else []
+
+
+# Directories never worth descending into when looking for nested skills.
+_IGNORED_DIRS = frozenset({".git", ".venv", "venv", "node_modules", "__pycache__", ".tox"})
+_STANDALONE_KINDS = frozenset({ArtifactKind.agent, ArtifactKind.skill, ArtifactKind.command})
+
+
+def _nested_skill_bases(start: Path) -> list[Path]:
+    """The `.claude` directories below `start`, for skills.
+
+    Skills (unlike agents) also load from nested `.claude/skills/` in subdirectories.
+
+    Args:
+        start: The directory to search beneath (resolved first).
+
+    Returns:
+        Every `.claude` strictly below `start`, sorted; the start's own `.claude` is excluded (it
+        is already an upward base) and noise dirs (`.git`, `node_modules`, …) are pruned.
+    """
+    start = start.resolve()
+    own = start / ".claude"
+    bases: list[Path] = []
+    for root, dirnames, _files in os.walk(start):
+        # prune in place so os.walk never descends into a noise tree at all — unlike rglob,
+        # which would first walk the whole subtree and only filter its matches afterward
+        dirnames[:] = [d for d in dirnames if d not in _IGNORED_DIRS]
+        if ".claude" in dirnames:
+            candidate = Path(root) / ".claude"
+            if candidate != own:
+                bases.append(candidate)
+    return sorted(bases)
+
+
+_MANAGED_DIRS: dict[str, Path] = {
+    "darwin": Path("/Library/Application Support/ClaudeCode"),
+    "linux": Path("/etc/claude-code"),
+    "win32": Path(r"C:\Program Files\ClaudeCode"),
+}
+
+
+def default_managed_dir() -> Path | None:
+    """The OS file-based managed-settings directory for this platform.
+
+    Only the file delivery mechanism is a path; MDM, registry, and server-delivered managed
+    settings are not files and cannot be scanned here.
+
+    Returns:
+        The platform's managed dir, or None on an unrecognised platform.
+    """
+    for prefix, path in _MANAGED_DIRS.items():
+        if sys.platform.startswith(prefix):
+            return path
+    return None
+
+
+class ScanRoot(FrozenModel):
+    """A real base directory to scan for a scope. `kinds` restricts which artifact kinds use it
+    (None = all): a nested-skill root serves only skills, a managed `.claude` only standalone
+    files, while the managed root itself serves the settings file."""
+
+    scope: ScopeKind
+    base: ScanBasePath
+    kinds: frozenset[ArtifactKind] | None = None
+
+
+class ScopeRoots(FrozenModel):
+    """The base directories to scan, in precedence order (highest first). Build with `discover`
+    so project scope is resolved by walking up to the repo root, not assumed to be the cwd."""
+
+    roots: list[ScanRoot] = []
+
+    @classmethod
+    def discover(
+        cls,
+        *,
+        start: Path,
+        home_dir: Path | None = None,
+        managed_dir: Path | None = None,
+        plugin_dirs: list[Path] | None = None,
+        add_dirs: list[Path] | None = None,
+    ) -> ScopeRoots:
+        """Resolve every scannable root from where Claude Code was started.
+
+        - project: every `.claude` from `start` up to the repo root (all kinds), plus every
+          `.claude` *below* `start` for skills, plus each `--add-dir`'s `.claude`.
+        - user / managed: included only when their dir is given — `discover` never auto-resolves
+          them. Managed splits: the dir itself holds `managed-settings.json`; its `.claude` holds
+          standalone files.
+        - plugin: the explicit `plugin_dirs` only.
+
+        Args:
+            start: The launch directory; project scope is resolved by walking up from here.
+            home_dir: The user's home; when given, its `.claude` is the user-scope root.
+            managed_dir: The OS managed dir; when given, it and its `.claude` are added (use
+                `default_managed_dir()` to obtain it).
+            plugin_dirs: Installed-plugin roots to scan; enabled-plugin resolution is the
+                caller's job, since plugins resolve through `enabledPlugins` + marketplaces.
+            add_dirs: Extra `--add-dir` roots; each contributes its `.claude` as project scope.
+
+        Returns:
+            The scan roots in precedence order, highest first.
+        """
+        plugin_dirs = plugin_dirs or []
+        add_dirs = add_dirs or []
+        roots: list[ScanRoot] = []
+        if managed_dir is not None:
+            roots.append(ScanRoot(scope=ScopeKind.managed, base=managed_dir))
+            roots.append(
+                ScanRoot(
+                    scope=ScopeKind.managed,
+                    base=managed_dir / ".claude",
+                    kinds=_STANDALONE_KINDS,
+                )
+            )
+        roots += [ScanRoot(scope=ScopeKind.project, base=base) for base in _project_bases(start)]
+        roots += [
+            ScanRoot(scope=ScopeKind.project, base=base, kinds=frozenset({ArtifactKind.skill}))
+            for base in _nested_skill_bases(start)
+        ]
+        # resolved, like _project_bases/_nested_skill_bases: an unresolved add-dir that's a
+        # symlink to (or through) `start` or another add-dir would otherwise scan the same
+        # physical directory twice, double-capturing every additive artifact it holds.
+        seen_project_bases = {
+            root.base.resolve() for root in roots if root.scope == ScopeKind.project
+        }
+        for add in add_dirs:
+            claude_dir = (add / ".claude").resolve()
+            if claude_dir.is_dir() and claude_dir not in seen_project_bases:
+                seen_project_bases.add(claude_dir)
+                roots.append(ScanRoot(scope=ScopeKind.project, base=claude_dir))
+        if home_dir is not None:
+            roots.append(ScanRoot(scope=ScopeKind.user, base=home_dir / ".claude"))
+        roots += [ScanRoot(scope=ScopeKind.plugin, base=plugin) for plugin in plugin_dirs]
+        return cls(roots=roots)

capdisc/scope/locations.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import Field, JsonValue, TypeAdapter, ValidationError
+
+from ..base import FrozenModel
+from .types import (
+    ARTIFACT_CONTENT_MAX_CHARS,
+    ArtifactContents,
+    ArtifactKind,
+    ArtifactName,
+    ArtifactPath,
+    ArtifactSubdir,
+    CliFlag,
+    GlobPattern,
+    JsonKey,
+    ResolutionMode,
+    ScopeKind,
+    ScopeRoot,
+    SettingsFile,
+    Shareability,
+)
+
+
+class CaptureHit(FrozenModel):
+    """One concrete definition a storage shape found under a real base path."""
+
+    path: ArtifactPath
+    name: ArtifactName
+    contents: ArtifactContents
+
+
+def _safe_read(path: Path, base: Path) -> str | None:
+    """Contents of `path` if it resolves inside `base`, is readable UTF-8, and fits the cap;
+    None to skip it. A dangling symlink, permission-denied, or non-UTF-8 file skips itself —
+    one bad file must never abort the scan.
+
+    Bounded to `ARTIFACT_CONTENT_MAX_CHARS` (the `ArtifactContents` cap) so an enormous file
+    cannot OOM the scan before validation; over-limit or symlink-escaping files are skipped,
+    not partially read."""
+    if not path.resolve().is_relative_to(base.resolve()):
+        return None
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            text = handle.read(ARTIFACT_CONTENT_MAX_CHARS + 1)
+    except (OSError, UnicodeDecodeError):
+        return None
+    return None if len(text) > ARTIFACT_CONTENT_MAX_CHARS else text
+
+
+_JSON_OBJECT: TypeAdapter[dict[str, JsonValue]] = TypeAdapter(dict[str, JsonValue])
+_JSON_VALUE: TypeAdapter[JsonValue] = TypeAdapter(JsonValue)
+
+
+def _extract_entry(text: str, key: JsonKey | None) -> str | None:
+    """The JSON slice a settings-entry artifact captures: the whole object when `key` is None
+    (a bare hooks.json), or that key's value (a `hooks` block inside settings.json). None when
+    the text is not a JSON object or the key is absent."""
+    try:
+        data = _JSON_OBJECT.validate_json(text)
+    except ValidationError:
+        return None
+    if key is None:
+        return text
+    if key not in data:
+        return None
+    return _JSON_VALUE.dump_json(data[key]).decode()
+
+
+# --- Axis 1: storage shape ------------------------------------------------------------
+# How a definition is physically stored — independent of which scope it sits in. Each shape
+# renders an abstract place (for the taxonomy) and discovers concrete hits (for a scan).
+
+
+class StandaloneFile(FrozenModel):
+    """A file of its own under <root>/<subdir>/ — agents, skills, commands."""
+
+    storage_kind: Literal["standalone_file"] = "standalone_file"
+    subdir: ArtifactSubdir
+    glob: GlobPattern
+    name_from: Literal["stem", "parent"] = "stem"
+
+    def discover(self, base: Path) -> list[CaptureHit]:
+        """Capture every file matching this shape's glob under `base/<subdir>`.
+
+        Args:
+            base: The scanned scope root; each hit's path must resolve inside it.
+
+        Returns:
+            One hit per readable, in-bounds file, named by stem or parent dir per `name_from`;
+            files that escape `base` or exceed the size cap are skipped.
+        """
+        directory = base / self.subdir
+        hits: list[CaptureHit] = []
+        for path in sorted(directory.glob(self.glob)):
+            contents = _safe_read(path, base)
+            if contents is None:
+                continue
+            name = path.parent.name if self.name_from == "parent" else path.stem
+            hits.append(CaptureHit(path=path, name=name, contents=contents))
+        return hits
+
+
+class SettingsEntry(FrozenModel):
+    """A key inside a JSON settings file — hooks, MCP servers, permissions. A None `key` means
+    the file's root object is the entry (a plugin's bare hooks.json), not a nested key."""
+
+    storage_kind: Literal["settings_entry"] = "settings_entry"
+    file: SettingsFile
+    key: JsonKey | None = None
+
+    def discover(self, base: Path) -> list[CaptureHit]:
+        """Capture this shape's settings entry from `base/<file>`.
+
+        Args:
+            base: The scanned scope root; the file's path must resolve inside it.
+
+        Returns:
+            A single hit holding the extracted entry (the whole object when `key` is None, else
+            that key's value), or `[]` if the file is missing, out of bounds, not JSON, or the
+            key is absent.
+        """
+        path = base / self.file
+        if not path.is_file():
+            return []
+        text = _safe_read(path, base)
+        if text is None:
+            return []
+        entry = _extract_entry(text, self.key)
+        if entry is None:
+            return []
+        return [CaptureHit(path=path, name=self.key or self.file, contents=entry)]
+
+
+class HostFrontmatter(FrozenModel):
+    """Embedded in another component's frontmatter — a hook defined inside a skill or agent."""
+
+    storage_kind: Literal["host_frontmatter"] = "host_frontmatter"
+    key: JsonKey
+
+    def discover(self, base: Path) -> list[CaptureHit]:  # noqa: ARG002 — uniform Storage interface
+        """Always empty — a frontmatter-embedded hook is captured with its host, not standalone."""
+        return []
+
+
+class InMemoryFlag(FrozenModel):
+    """Supplied as JSON on a launch flag — the --agents session form."""
+
+    storage_kind: Literal["in_memory_flag"] = "in_memory_flag"
+    flag: CliFlag
+
+    def discover(self, base: Path) -> list[CaptureHit]:  # noqa: ARG002 — uniform Storage interface
+        """Always empty — a launch-flag definition lives in process memory, not on disk."""
+        return []
+
+
+Storage = Annotated[
+    StandaloneFile | SettingsEntry | HostFrontmatter | InMemoryFlag,
+    Field(discriminator="storage_kind"),
+]
+
+
+# --- Axis 2: location -----------------------------------------------------------------
+# A concrete place a definition can live: a scope, how it is shared, the root it sits under,
+# and the storage shape. Scope is a property of location, not the organizing axis. Precedence
+# is NOT a property of a scope: it differs by artifact kind, so it lives in the order each
+# artifact lists its locations (Axis 3), not in a table here.
+
+
+class Location(FrozenModel):
+    """Where a definition lives, and what that implies — scope, shareability, storage shape."""
+
+    scope: ScopeKind
+    shareable: Shareability
+    root: ScopeRoot
+    storage: Storage
+
+
+# --- Axis 3: artifact -----------------------------------------------------------------
+# What is stored. Each kind declares the locations it can live in — listed highest-precedence
+# first, so the order *is* the name-collision precedence. That order differs by kind: subagents
+# rank project over user, skills and commands the reverse; only subagents have the --agents
+# session scope; commands have no managed/enterprise location.
+
+
+def _standalone(
+    subdir: ArtifactSubdir, glob: GlobPattern, name_from: Literal["stem", "parent"]
+) -> StandaloneFile:
+    """A standalone-file storage shape under `<root>/<subdir>` matching `glob`."""
+    return StandaloneFile(subdir=subdir, glob=glob, name_from=name_from)
+
+
+def _managed(shape: StandaloneFile) -> Location:
+    """The managed (admin) location for `shape`, under `<managed>/.claude`."""
+    return Location(
+        scope=ScopeKind.managed,
+        shareable=Shareability.admin,
+        root="<managed>/.claude",
+        storage=shape,
+    )
+
+
+def _project(shape: StandaloneFile) -> Location:
+    """The project (committed) location for `shape`, under `.claude`."""
+    return Location(
+        scope=ScopeKind.project, shareable=Shareability.committed, root=".claude", storage=shape
+    )
+
+
+def _user(shape: StandaloneFile) -> Location:
+    """The user (machine-local) location for `shape`, under `~/.claude`."""
+    return Location(
+        scope=ScopeKind.user, shareable=Shareability.machine_local, root="~/.claude", storage=shape
+    )
+
+
+def _plugin(shape: StandaloneFile) -> Location:
+    """The plugin (bundled) location for `shape`, under the plugin root."""
+    return Location(
+        scope=ScopeKind.plugin, shareable=Shareability.bundled, root="<plugin>", storage=shape
+    )
+
+
+def _session() -> Location:
+    """The session (ephemeral) `--agents` location — an in-memory flag, no disk root."""
+    return Location(
+        scope=ScopeKind.session,
+        shareable=Shareability.ephemeral,
+        root="(--agents)",
+        storage=InMemoryFlag(flag="--agents"),
+    )
+
+
+_AGENT_FILE = _standalone("agents", "**/*.md", "stem")
+_SKILL_FILE = _standalone("skills", "**/SKILL.md", "parent")
+_COMMAND_FILE = _standalone("commands", "**/*.md", "stem")
+
+
+class Subagent(FrozenModel):
+    """The subagent artifact `.md` files, on a collision; locations are highest-precedence first
+    (managed, then the `--agents` session scope, then project over user, then plugin)."""
+
+    kind: Literal[ArtifactKind.agent] = ArtifactKind.agent
+    resolution: Literal[ResolutionMode.collision] = ResolutionMode.collision
+    locations: list[Location] = [
+        _managed(_AGENT_FILE),
+        _session(),
+        _project(_AGENT_FILE),
+        _user(_AGENT_FILE),
+        _plugin(_AGENT_FILE),
+    ]
+
+
+class Skill(FrozenModel):
+    """The skill `SKILL.md` files, on a collision; locations are highest-precedence first
+    (managed, then user over project — the reverse of subagents — then plugin)."""
+
+    kind: Literal[ArtifactKind.skill] = ArtifactKind.skill
+    resolution: Literal[ResolutionMode.collision] = ResolutionMode.collision
+    locations: list[Location] = [
+        _managed(_SKILL_FILE),
+        _user(_SKILL_FILE),
+        _project(_SKILL_FILE),
+        _plugin(_SKILL_FILE),
+    ]
+
+
+class Command(FrozenModel):
+    """The command `.md` files, on a collision; locations are highest-precedence first (user,
+    project, plugin) — commands have no managed/enterprise location."""
+
+    kind: Literal[ArtifactKind.command] = ArtifactKind.command
+    resolution: Literal[ResolutionMode.collision] = ResolutionMode.collision
+    locations: list[Location] = [
+        _user(_COMMAND_FILE),
+        _project(_COMMAND_FILE),
+        _plugin(_COMMAND_FILE),
+    ]
+
+
+class Hook(FrozenModel):
+    """A hook is never a file of its own: it is a settings entry, a bundled hooks.json, or a
+    key in a host component's frontmatter. Its scope follows where it is written."""
+
+    kind: Literal[ArtifactKind.hook] = ArtifactKind.hook
+    resolution: Literal[ResolutionMode.additive] = ResolutionMode.additive
+    locations: list[Location] = [
+        Location(
+            scope=ScopeKind.user,
+            shareable=Shareability.machine_local,
+            root="~/.claude",
+            storage=SettingsEntry(file="settings.json", key="hooks"),
+        ),
+        Location(
+            scope=ScopeKind.project,
+            shareable=Shareability.committed,
+            root=".claude",
+            storage=SettingsEntry(file="settings.json", key="hooks"),
+        ),
+        Location(
+            scope=ScopeKind.project,
+            shareable=Shareability.gitignored,
+            root=".claude",
+            storage=SettingsEntry(file="settings.local.json", key="hooks"),
+        ),
+        Location(
+            scope=ScopeKind.managed,
+            shareable=Shareability.admin,
+            root="<managed>",
+            storage=SettingsEntry(file="managed-settings.json", key="hooks"),
+        ),
+        Location(
+            scope=ScopeKind.plugin,
+            shareable=Shareability.bundled,
+            root="<plugin>",
+            storage=SettingsEntry(file="hooks/hooks.json", key=None),
+        ),
+        Location(
+            scope=ScopeKind.component,
+            shareable=Shareability.in_component,
+            root="(host)",
+            storage=HostFrontmatter(key="hooks"),
+        ),
+    ]
+
+
+Artifact = Annotated[Subagent | Skill | Command | Hook, Field(discriminator="kind")]
+"""A scoped artifact kind, dispatched on `kind`."""