[
  {
    "type": "case",
    "title": "Three avatar candidates redrawn with one Riso contract",
    "description": "Three authorized single-person photos with different poses, hair and backgrounds were each redrawn through gpt-image-2. The comparison verifies that identity, gaze and clothing cues survive while the visual medium changes to limited inks, halftone and paper grain.",
    "input": {
      "items": [
        "Three authorized source portraits supplied for avatar selection",
        "Square avatar use with identity, pose, gaze and clothing locked"
      ]
    },
    "prompt": "使用 Riso 人像 Skill 处理这些照片。保持人物身份、脸部结构、发型、视线和服装不变，裁成适合圆形头像的近景，使用朱红与深青主墨色，并保留纸张颗粒、网点和轻微套印偏移。",
    "output": {
      "items": [
        "cases/artifacts/avatar-source-and-riso.jpg",
        "A 2 by 3 source/result comparison with three recognizable Riso portraits"
      ]
    },
    "cover": "cases/artifacts/avatar-source-and-riso.jpg"
  },
  {
    "type": "case",
    "title": "Targeted correction from four fingers to five",
    "description": "An authorized event portrait already had a strong Riso treatment, but the raised hand contained four fingers. A single-fact correction restored five fingers while preserving the person, pose, microphone, clothing and style.",
    "input": {
      "items": [
        "Authorized event source photo",
        "First Riso output with an incorrect raised hand"
      ]
    },
    "prompt": "只修正右上方的手，必须是五根手指；其他人物特征、动作、构图和 Riso 风格保持不变。",
    "output": {
      "items": [
        "cases/artifacts/five-finger-correction.jpg",
        "Source, four-finger first pass and verified five-finger correction with detail crops"
      ]
    },
    "cover": "cases/artifacts/five-finger-correction.jpg"
  }
]

# Riso 人像的三种实现路径

这三种路径解决的是不同目标，彼此并列，不使用“先……再……”把它们写成固定流程。

## 1. 程序化滤镜

对原图做主体分割、调色、阈值、网点、纸张纹理和套印偏移。优点是速度快、参数稳定、
可批量复现；缺点是仍以原像素为基础，难以重新设计线条、色块、负空间和人物轮廓。
它适合“可控的 Riso-like 图像处理”，不能冒充生成模型完成的插画重绘。

## 2. 生成模型重绘

把原图作为 edit target 与 identity reference，由 `gpt-image-2` 重组线稿、有限色墨、
网点与纸张关系。它更容易得到完整的插画语言，也是本 Skill 默认路径；代价是结果存在
随机性，可能产生脸部漂移、手指数目、饰品或物件等常识性错误，因此必须逐项验收。

不要完全信任生成模型。发现错误时以源图和真实世界事实为准，只修错误区域，并明确
要求其他身份、动作、构图与风格保持不变。

## 3. AI 分析参数 + 确定性渲染

先让视觉模型分析源图并输出结构化参数，再由程序化管线确定性执行。建议参数至少包括：

- 主体蒙版、背景处理方式与边缘羽化；
- 墨色数量与具体色值；
- 阈值、对比度、亮暗分区与网点密度；
- 线条强度、纸张纹理、套印方向和偏移量；
- 头像安全区、裁切中心与视线留白。

该路径把大模型的图像理解与程序化渲染的可控性结合起来，适合批量一致性和参数复现，
也可能减少生成模型的解剖错误。它目前是值得探索的研究方向，不得在没有真实实现与
验收证据时写成已经完成或优于默认重绘。

# Riso Portrait Quality Gate

## Identity

- The face is immediately recognizable as the same person at full size and avatar size.
- Face shape, eyes, nose, lips, jaw, apparent age, expression and skin-tone family remain stable.
- Hair silhouette, parting and visible hair accessories remain consistent with the source.

## Scene facts

- Pose, gaze direction, clothing, jewelry, glasses and held objects are preserved.
- Every visible hand has the correct number and arrangement of fingers.
- No extra people, limbs, accessories, text, Logo or watermark were introduced.

## Riso medium

- The image uses a limited spot-color palette rather than continuous photographic color.
- Shadows are expressed through halftone or graphic shapes, not a gray photo layer.
- Paper grain, imperfect ink edges and registration offset are visible but restrained.
- The result reads as a hand-drawn editorial Riso portrait, not anime, 3D art or a filtered photo.

## Avatar crop

- The square frame leaves the full hair silhouette and chin intact.
- A centered circular crop keeps the face and gaze readable.
- The direction in front of the gaze retains enough breathing room.
- At chat-list size, facial identity and the main ink contrast remain legible.

## Correction gate

If any check fails, make one targeted correction and repeat all four groups. Do not accept an
attractive overall image as evidence that anatomy, identity or crop is correct.

# Riso Portrait Art Direction

## Accepted visual contract

Use the uploaded image as both the edit target and the identity reference. Ask `gpt-image-2`
to translate the visual medium while keeping the person and scene facts stable.

The prompt should express this contract in natural language:

```text
Use case: style-transfer
Asset type: 1:1 social profile avatar
Input image: The uploaded image is the edit target and identity reference.
Primary request: Turn the main subject into a friendly hand-drawn Riso cartoon portrait with bold black outlines, limited spot colors, halftone texture and a simple rounded card background. Preserve identity and key features.
Style/medium: authentic hand-printed Risograph portrait, flat graphic shapes, visible paper grain, halftone dots, bold imperfect ink edges, subtle 4 px registration offset; refined editorial illustration rather than a generic digital filter.
Composition/framing: square close head-and-shoulders portrait optimized for a circular avatar; keep the source pose and gaze direction, preserve the full hair silhouette, and leave comfortable space in front of the gaze.
Color palette: deep charcoal #182A2D, teal #087E8B, vermilion #EF542F, warm paper #F5DFBF.
Constraints: Preserve the exact person's recognizable face shape, eyes, nose, lips, expression, hairstyle, skin proportions, pose, clothing cues, accessories and held objects. Keep identity stable while translating only the visual medium. No facial beautification, age change, pose change, extra accessories or extra people.
Avoid: photorealism, anime style, plastic skin, glossy 3D rendering, text, logos, watermark, white circular cutout, ornate frame.
```

Append a short `Creator note` only when the user supplies a real preference, such as a cleaner
background, a specific two-ink palette, or a tighter crop. The note cannot cancel the identity,
anatomy, composition, or no-text constraints.

## Why direct redraw matters

Riso portrait quality comes from decisions about flat shapes, line weight, ink coverage, negative
space and halftone shadows. A post-processing pipeline can recolor pixels and add dots, but it
cannot reliably redesign those relationships. Do not add Canvas, Sharp, CSS, color-separation or
noise passes after generation.

## Iteration contract

- One correction per pass.
- Repeat every invariant in a correction Prompt.
- When the problem is local, identify the exact region and fact.
- Never describe a new generation as fixed until the corrected detail has been visually inspected.

# LovStudio Skill Card standard

`skill-card.yaml` follows the minimum release-record idea of NVIDIA Skill Cards:
description, owner, license/terms, use case, deployment, requirements,
risks/mitigations, references, output contract, version, and ethical
considerations. LovStudio adds evidence that helps a user decide whether the
Skill is credible:

1. A real user case with Input → Prompt → Output.
2. A dimension map with named evidence, not an unexplained score.
3. A pricing basis, including the free boundary and review trigger.
4. Explicit paid and free distribution states.

Never claim a case, score, channel, or price that has not been verified.

# Skill Group Composition

## Nearby Skills Inspected

- `lov-professional-portrait`：保留照片媒介，负责职业照精修、提亮、去帽和背景整理；
  它不生成 Riso 插画，因此不是重叠实现。
- `lov-image-creator`：通用生图、代码渲染和 Prompt 工程框架；它可以提供图像工具，
  但不拥有身份保真的 Riso 头像验收。
- `lov-style-clone`：从文章提炼写作文风并改写文本；输入输出都不是人像图片，不组合。
- 运行中的 Imagine `Riso 人像工坊`：产品内的真实实现证据，使用 `gpt-image-2`、
  高输入保真度和同一视觉基准；它不是安装式 sibling Skill。

## Atomic Handoffs

- 上游输入由用户或照片选择能力提供一张获得授权的单人图片；本 Skill 从身份检查开始负责。
- 核心原子是 `lov-riso-portrait`：输入原图和最小 brief，输出通过人物、Riso 媒介、
  事实细节与头像裁切验收的 PNG。
- 下游 `lov-image-decorator`、文章排版、社交发布或头像上传能力可以消费最终 PNG；
  它们不能替代本 Skill 的身份与解剖检查。
- `lov-professional-portrait` 可在用户明确要求时先修复曝光或背景，但其输出必须重新
  作为本 Skill 的唯一 identity reference，不能在两项能力之间隐式混合身份。

## Overlap Decisions

没有发现拥有同一结果契约的独立 Skill。通用生图不能保证采用 `gpt-image-2`，职业照
保持照片媒介，Imagine 则是产品运行实现。新 Skill 复用已验收的视觉契约和质量门，
不复制 Imagine 的任务持久化、鉴权或服务端代码。

## Composition Decision

本源是 Single Skill。原图检查、Prompt 约束、直接重绘、三尺度验收和局部修正共同
服务一个头像结果，拆成 Kit 会增加身份漂移风险。相邻能力均通过图片文件可选交接。

# User Profile contract

Every Skill created by Skill Creator declares `user-profile/v1` in `skill.yaml`.
The contract connects independent sessions to one user-owned JSON Profile while
keeping the Skill source portable across users and brands.

## Shared shape

The host supplies the Profile through `SKILL_PROFILE_PATH` (or the runtime's
configured profile path). The stable shared scopes are:

- `user`: user identity, language, timezone, and other personal working defaults.
- `brand`: public brand facts, site, logo, tone, profile, and design guidance.
- `workspace`: project roots and output locations.
- `preferences`: shared preference values when the host stores them in the Profile.
- `skills.<skill_id>.profile`: Skill-specific defaults.
- `skills.<skill_id>.records`: durable decisions and preferences learned from
  direct user statements for this Skill.

The Profile may also use the runtime's canonical `identity` fields. Manifest
field aliases bridge `identity.*` and the portable `user.*` / `brand.*` names.

## Read on every run

1. Read the current request and project context.
2. Read the shared Profile and the `skills.<skill_id>` namespace.
3. Resolve values in this order: current request, project context, Skill records,
   shared preferences, shared user/brand Profile, safe defaults.
4. Keep `profile_scope` and field provenance available for the final result.

Do not copy resolved personal paths, brand values, or private records into the
committed Skill source.

## Persist directly stated values

When the user explicitly gives a value meant to survive later sessions, save it
immediately after the user statement and report the canonical path:

```bash
python3 scripts/profile_store.py record \
  --skill-id lov-example \
  --path records.subtitle_level \
  --value '"cet4"' \
  --confirm
```

For shared facts, use `--path brand.<field>` or `--path user.<field>`. The
script writes JSON atomically, preserves unrelated Profile data, increments a
numeric Profile revision when present, and never echoes the stored value.

Inferred information, credentials, tokens, cookies, and secret-like fields stay
out of durable records. If the user has not stated that a value should persist,
keep it in the current request context.

## Read the connected context

```bash
python3 scripts/profile_store.py read \
  --skill-id lov-example \
  --pretty
```

The result contains `user`, `brand`, `workspace`, `preferences`, `skill`, and
`records` scopes. A host using `skill-runtime/v1` also returns the same binding
as `profile_scope` and `profile_contract`.

## Compatibility

`--user-config` remains accepted by the Creator as a compatibility flag for old
invocations. The Profile contract is now always generated; users do not choose
an initialization mode.

#!/usr/bin/env python3
"""Read and persist a Skill's user-owned profile context.

The command keeps shared identity and brand facts in the profile root while
putting Skill-specific durable records under ``skills.<skill_id>.records``.
Writes require an explicit confirmation flag and use an atomic replacement.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
import tempfile
from pathlib import Path
from typing import Any, Iterable


USER_PROFILE_SCHEMA = "user-profile/v1"
SKILL_ID_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
SAFE_ROOTS = {"user", "brand", "workspace", "preferences"}
SENSITIVE_PARTS = {"token", "secret", "password", "credential", "cookie", "api_key", "apikey"}


def config_dir() -> Path:
    configured = os.environ.get("SKILLS_CONFIG_DIR")
    if configured:
        return Path(os.path.expandvars(configured)).expanduser()
    xdg = os.environ.get("XDG_CONFIG_HOME")
    if xdg:
        return Path(os.path.expandvars(xdg)).expanduser() / "agent-skills"
    return Path.home() / ".config" / "agent-skills"


def profile_path(explicit: Path | None = None) -> Path:
    if explicit:
        return explicit.expanduser()
    configured = (
        os.environ.get("SKILL_PROFILE_PATH")
        or os.environ.get("SKILLS_PROFILE_PATH")
    )
    if configured:
        return Path(os.path.expandvars(configured)).expanduser()
    candidates = (
        Path.home() / ".lovstudio" / "skills" / "profile.json",
        Path.home() / ".skill-publisher" / "skills" / "profile.json",
        config_dir() / "profile.json",
    )
    return next((candidate for candidate in candidates if candidate.exists()), candidates[-1])


def read_profile(path: Path) -> dict[str, Any]:
    if not path.exists():
        return {}
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile cannot be read: {path}: {exc}") from exc
    if not isinstance(value, dict):
        raise ValueError("profile root must be an object")
    return value


def profile_skeleton(skill_id: str) -> dict[str, Any]:
    return {
        "schema": "skill-profile/v1",
        "profile_id": f"profile-{skill_id}",
        "revision": 1,
        "status": "draft",
        "identity": {},
        "purpose": {},
        "brand": {},
        "user": {},
        "workspace": {},
        "skills": {},
        "extensions": {},
    }


def atomic_write(path: Path, value: dict[str, Any]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    mode = 0o600
    if path.exists():
        mode = path.stat().st_mode & 0o777
    temporary_name: str | None = None
    try:
        with tempfile.NamedTemporaryFile(
            "w",
            encoding="utf-8",
            dir=path.parent,
            prefix=f".{path.name}.",
            suffix=".tmp",
            delete=False,
        ) as handle:
            temporary_name = handle.name
            handle.write(json.dumps(value, ensure_ascii=False, indent=2) + "\n")
            handle.flush()
            os.fsync(handle.fileno())
        os.chmod(temporary_name, mode)
        os.replace(temporary_name, path)
    finally:
        if temporary_name:
            temporary = Path(temporary_name)
            if temporary.exists():
                temporary.unlink()


def set_path(root: dict[str, Any], parts: list[str], value: Any) -> None:
    current: dict[str, Any] = root
    for part in parts[:-1]:
        child = current.get(part)
        if not isinstance(child, dict):
            child = {}
            current[part] = child
        current = child
    current[parts[-1]] = value


def target_parts(skill_id: str, requested_path: str) -> tuple[list[str], str]:
    if not SKILL_ID_RE.fullmatch(skill_id):
        raise ValueError("skill_id must be kebab-case")
    path = requested_path.strip().strip(".")
    if not path:
        raise ValueError("path is required")
    parts = [part for part in path.split(".") if part]
    if any(not re.fullmatch(r"[A-Za-z0-9_-]+", part) for part in parts):
        raise ValueError("path contains an invalid segment")
    if any(part.casefold() in SENSITIVE_PARTS for part in parts):
        raise ValueError("profile records do not accept secret-like fields")

    if parts[0] == "records":
        target = ["skills", skill_id, "records", *parts[1:]]
        return target, ".".join(target)
    if parts[0] == "profile":
        target = ["skills", skill_id, "profile", *parts[1:]]
        return target, ".".join(target)
    if parts[:3] == ["skills", skill_id, "records"]:
        return parts, ".".join(parts)
    if parts[:3] == ["skills", skill_id, "profile"]:
        return parts, ".".join(parts)
    if parts[0] in SAFE_ROOTS:
        return parts, ".".join(parts)
    expected = f"records.<field> or one of: {', '.join(sorted(SAFE_ROOTS))}.<field>"
    raise ValueError(f"path must use {expected}")


def parse_value(raw: str) -> Any:
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        return raw


def read_command(args: argparse.Namespace) -> dict[str, Any]:
    path = profile_path(args.profile)
    profile = read_profile(path)
    skills = profile.get("skills", {})
    if not isinstance(skills, dict):
        skills = {}
    skill = skills.get(args.skill_id, {})
    if not isinstance(skill, dict):
        skill = {}
    user = profile.get("user")
    if not isinstance(user, dict) or not user:
        user = profile.get("identity", {})
    if not isinstance(user, dict):
        user = {}
    brand = profile.get("brand", {})
    if not isinstance(brand, dict):
        brand = {}
    workspace = profile.get("workspace", {})
    if not isinstance(workspace, dict):
        workspace = {}
    preferences = profile.get("preferences", {})
    if not isinstance(preferences, dict):
        preferences = {}
    records = skill.get("records", {})
    if not isinstance(records, dict):
        records = {}
    return {
        "status": "ready",
        "schema": USER_PROFILE_SCHEMA,
        "skill_id": args.skill_id,
        "profile_path": str(path),
        "user": user,
        "brand": brand,
        "workspace": workspace,
        "preferences": preferences,
        "skill": skill,
        "records": records,
    }


def record_command(args: argparse.Namespace) -> dict[str, Any]:
    if not args.confirm:
        raise PermissionError("record requires --confirm after the user has stated the value")
    parts, canonical_path = target_parts(args.skill_id, args.path)
    path = profile_path(args.profile)
    profile = read_profile(path)
    if not profile:
        profile = profile_skeleton(args.skill_id)
    set_path(profile, parts, parse_value(args.value))
    revision = profile.get("revision")
    if isinstance(revision, int) and not isinstance(revision, bool):
        profile["revision"] = revision + 1
    atomic_write(path, profile)
    return {
        "status": "saved",
        "schema": USER_PROFILE_SCHEMA,
        "skill_id": args.skill_id,
        "profile_path": str(path),
        "path": canonical_path,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--profile", type=Path, default=None, help="Shared profile JSON path")
    subparsers = parser.add_subparsers(dest="command", required=True)

    read_parser = subparsers.add_parser("read", help="Read shared and Skill-specific profile context")
    read_parser.add_argument("--skill-id", required=True)
    read_parser.add_argument("--pretty", action="store_true")

    record_parser = subparsers.add_parser("record", help="Persist a user-stated profile value")
    record_parser.add_argument("--skill-id", required=True)
    record_parser.add_argument("--path", required=True, help="records.<field>, brand.<field>, or user.<field>")
    record_parser.add_argument("--value", required=True)
    record_parser.add_argument("--confirm", action="store_true")

    args = parser.parse_args()
    try:
        result = read_command(args) if args.command == "read" else record_command(args)
    except (OSError, PermissionError, ValueError) as exc:
        print(json.dumps({"status": "error", "error": str(exc)}, ensure_ascii=False), file=sys.stderr)
        return 2
    indent = 2 if getattr(args, "pretty", False) else None
    print(json.dumps(result, ensure_ascii=False, indent=indent, sort_keys=bool(indent)))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Validate a portable local Skill Publisher Skill source directory."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any, Iterable

try:
    import yaml
except ImportError:
    print(
        "ERROR: PyYAML is required. Install it with: python3 -m pip install PyYAML",
        file=sys.stderr,
    )
    raise SystemExit(2)


FRONTMATTER_KEYS = {
    "name",
    "description",
    "license",
    "compatibility",
    "allowed-tools",
    "depends_on",
    "metadata",
}
TEXT_SUFFIXES = {".md", ".json", ".yaml", ".yml", ".txt", ".svg", ".py"}
JUNK_NAMES = {"__pycache__", ".DS_Store"}
JUNK_SUFFIXES = {".pyc", ".pyo"}
SKIP_DIRS = {".git", "dist", ".venv", "venv", "node_modules"}
SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$")
NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
MARKDOWN_LINK_RE = re.compile(r"!?\[[^\]]*]\(([^)]+)\)")
SKILL_PATH_RE = re.compile(r"\$(SKILL_DIR|KIT_DIR)/([A-Za-z0-9_./-]+)")
CARD_STANDARD = "lovstudio/skill-card/v1"
PRICING_CARD_SCHEMA = "lovstudio/pricing-card/v1"
MANIFEST_SCHEMA = "skill-manifest/v1"
RUNTIME_VERSION = "skill-runtime/v1"
PROFILE_SCHEMA = "user-profile/v1"
CONTENT_CLASSES = {
    "authored-prose",
    "microcopy",
    "verbatim",
    "deterministic-output",
}


class ValidationFailure(Exception):
    """Raised when source metadata cannot be parsed."""


def read_text(path: Path) -> str:
    return path.read_text(encoding="utf-8")


def compact_text(value: Any) -> str:
    return re.sub(r"\s+", " ", value).strip() if isinstance(value, str) else ""


def split_frontmatter(path: Path) -> tuple[dict[str, Any], str]:
    text = read_text(path)
    if not text.startswith("---\n"):
        raise ValidationFailure(f"{path}: missing YAML frontmatter")
    marker = text.find("\n---\n", 4)
    if marker < 0:
        raise ValidationFailure(f"{path}: frontmatter is not closed")
    try:
        data = yaml.safe_load(text[4:marker])
    except yaml.YAMLError as exc:
        raise ValidationFailure(
            f"{path}: standard YAML parser rejected frontmatter: {exc}"
        ) from exc
    if not isinstance(data, dict):
        raise ValidationFailure(f"{path}: frontmatter must be a mapping")
    return data, text[marker + 5 :]


def iter_files(root: Path) -> Iterable[Path]:
    for path in root.rglob("*"):
        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
            continue
        if path.is_file():
            yield path


def is_relative_to(path: Path, parent: Path) -> bool:
    try:
        path.relative_to(parent)
        return True
    except ValueError:
        return False


def validate_skill_file(path: Path, errors: list[str]) -> dict[str, Any] | None:
    try:
        data, body = split_frontmatter(path)
    except ValidationFailure as exc:
        errors.append(str(exc))
        return None

    unexpected = sorted(set(data) - FRONTMATTER_KEYS)
    if unexpected:
        errors.append(f"{path}: unsupported frontmatter keys: {', '.join(unexpected)}")

    name = compact_text(data.get("name"))
    if not NAME_RE.fullmatch(name) or len(name) > 64:
        errors.append(f"{path}: name must be kebab-case and at most 64 characters")

    description = compact_text(data.get("description"))
    if not 50 <= len(description) <= 200:
        errors.append(
            f"{path}: description must contain 50-200 characters "
            f"(found {len(description)})"
        )

    compatibility = compact_text(data.get("compatibility"))
    if not compatibility:
        errors.append(f"{path}: compatibility is required at the top level")

    depends_on = data.get("depends_on", [])
    if isinstance(depends_on, str):
        depends_on = [depends_on]
    if not isinstance(depends_on, list) or not all(
        isinstance(item, str) and NAME_RE.fullmatch(item) for item in depends_on
    ):
        errors.append(f"{path}: depends_on must be a list of exact Skill names")

    metadata = data.get("metadata")
    if not isinstance(metadata, dict):
        errors.append(f"{path}: metadata must be a mapping")
    else:
        if not compact_text(metadata.get("author")):
            errors.append(f"{path}: metadata.author is required")
        if not SEMVER_RE.fullmatch(compact_text(metadata.get("version"))):
            errors.append(f"{path}: metadata.version must use SemVer")
        tags = metadata.get("tags")
        if not isinstance(tags, list) or not tags or not all(
            isinstance(tag, str) and tag.strip() for tag in tags
        ):
            errors.append(f"{path}: metadata.tags must be a non-empty list")
        if "card_standard" in metadata and metadata.get("card_standard") != CARD_STANDARD:
            errors.append(f"{path}: metadata.card_standard must be {CARD_STANDARD}")
        content_class = compact_text(metadata.get("content_class"))
        if content_class and content_class not in CONTENT_CLASSES:
            errors.append(
                f"{path}: metadata.content_class must be one of "
                f"{', '.join(sorted(CONTENT_CLASSES))}"
            )
        if content_class in {"authored-prose", "microcopy"} and (
            not isinstance(depends_on, list)
            or "lov-branding-consistency" not in depends_on
        ):
            errors.append(
                f"{path}: {content_class} requires lov-branding-consistency"
            )
        if content_class == "authored-prose":
            authorship_reference = path.parent / "references" / "authorship-integrity.md"
            if not authorship_reference.is_file():
                errors.append(
                    f"{authorship_reference}: authored-prose contract is required"
                )
            if "references/authorship-integrity.md" not in body:
                errors.append(
                    f"{path}: authored-prose must route to references/authorship-integrity.md"
                )

    trigger_block = re.search(
        r"(?ms)^##\s+Triggers\s*$([\s\S]*?)(?=^##\s+|\Z)", body
    )
    if not trigger_block:
        errors.append(f"{path}: add an explicit '## Triggers' section")
    else:
        block = trigger_block.group(1)
        if len(re.findall(r"(?m)^\s*-\s+\S", block)) < 3:
            errors.append(f"{path}: add two activation examples and one non-trigger")
        if not re.search(r"[\u3400-\u9fff]", block):
            errors.append(f"{path}: add a concrete Chinese trigger phrase")
        if not re.search(r"(?i)\b(?:the|a|an|create|build|help|publish|review|use)\b", block):
            errors.append(f"{path}: add a concrete English trigger phrase")
    if not re.search(
        r"(?mi)^###\s+(?:Do not activate when|Non-triggers?|不应触发|不要触发)\s*$",
        body,
    ):
        errors.append(f"{path}: add explicit non-trigger conditions")
    if len(read_text(path).splitlines()) >= 500:
        errors.append(f"{path}: keep SKILL.md below 500 lines")
    if not body.strip():
        errors.append(f"{path}: body is empty")
    return data


def load_yaml(path: Path, errors: list[str]) -> dict[str, Any] | None:
    try:
        data = yaml.safe_load(read_text(path))
    except yaml.YAMLError as exc:
        errors.append(f"{path}: standard YAML parser rejected file: {exc}")
        return None
    if not isinstance(data, dict):
        errors.append(f"{path}: expected a YAML mapping")
        return None
    return data


def validate_runtime_manifest(
    skill_root: Path, expected_skill_id: str, errors: list[str]
) -> None:
    manifest_path = skill_root / "skill.yaml"
    if not manifest_path.is_file():
        errors.append(f"{manifest_path}: user-profile runtime manifest is required")
        return
    data = load_yaml(manifest_path, errors)
    if data is None:
        return
    if data.get("schema") != MANIFEST_SCHEMA:
        errors.append(f"{manifest_path}: schema must be {MANIFEST_SCHEMA}")
    if data.get("id") != expected_skill_id:
        errors.append(f"{manifest_path}: id must match {expected_skill_id}")
    version = compact_text(data.get("version"))
    if not SEMVER_RE.fullmatch(version):
        errors.append(f"{manifest_path}: version must use SemVer")
    if data.get("runtime") != RUNTIME_VERSION:
        errors.append(f"{manifest_path}: runtime must be {RUNTIME_VERSION}")

    context = data.get("context")
    if not isinstance(context, dict):
        errors.append(f"{manifest_path}: context must be a mapping")
        return
    profile = context.get("profile")
    preferences = context.get("preferences")
    interaction = context.get("interaction")
    if not isinstance(profile, dict):
        errors.append(f"{manifest_path}: context.profile must be a mapping")
    else:
        if profile.get("schema") != PROFILE_SCHEMA:
            errors.append(f"{manifest_path}: context.profile.schema must be {PROFILE_SCHEMA}")
        if profile.get("source") != "shared-profile":
            errors.append(f"{manifest_path}: context.profile.source must be shared-profile")
        reads = profile.get("read")
        if not isinstance(reads, list) or not reads or not all(
            isinstance(item, str) and item.strip() for item in reads
        ):
            errors.append(f"{manifest_path}: context.profile.read must be a non-empty list")
        persist = profile.get("persist")
        if not isinstance(persist, dict):
            errors.append(f"{manifest_path}: context.profile.persist must be a mapping")
        else:
            if persist.get("enabled") is not True:
                errors.append(f"{manifest_path}: profile persistence must be enabled")
            if persist.get("namespace") != f"skills.{expected_skill_id}":
                errors.append(f"{manifest_path}: persist.namespace must target skills.{expected_skill_id}")
            if persist.get("records_path") != f"skills.{expected_skill_id}.records":
                errors.append(f"{manifest_path}: persist.records_path must target Skill records")
            if persist.get("write_policy") != "direct-user-statement":
                errors.append(f"{manifest_path}: persist.write_policy must be direct-user-statement")
            if persist.get("atomic") is not True:
                errors.append(f"{manifest_path}: profile persistence must be atomic")
        fields = profile.get("fields")
        if not isinstance(fields, list) or not fields:
            errors.append(f"{manifest_path}: context.profile.fields must be a non-empty list")
        else:
            validate_manifest_fields(manifest_path, "profile", fields, errors)
    if not isinstance(preferences, dict):
        errors.append(f"{manifest_path}: context.preferences must be a mapping")
    else:
        fields = preferences.get("fields")
        if not isinstance(fields, list):
            errors.append(f"{manifest_path}: context.preferences.fields must be a list")
        else:
            validate_manifest_fields(manifest_path, "preferences", fields, errors)
    if not isinstance(interaction, dict):
        errors.append(f"{manifest_path}: context.interaction must be a mapping")
    else:
        if not isinstance(interaction.get("ask_missing"), bool):
            errors.append(f"{manifest_path}: interaction.ask_missing must be boolean")
        max_questions = interaction.get("max_questions")
        if not isinstance(max_questions, int) or isinstance(max_questions, bool) or not 1 <= max_questions <= 3:
            errors.append(f"{manifest_path}: interaction.max_questions must be 1-3")


def validate_manifest_fields(
    manifest_path: Path, source_name: str, fields: list[Any], errors: list[str]
) -> None:
    for index, field in enumerate(fields):
        label = f"{manifest_path}: context.{source_name}.fields[{index}]"
        if not isinstance(field, dict):
            errors.append(f"{label} must be a mapping")
            continue
        if not compact_text(field.get("path")):
            errors.append(f"{label}.path is required")
        if not isinstance(field.get("required"), bool):
            errors.append(f"{label}.required must be boolean")
        if not compact_text(field.get("question")):
            errors.append(f"{label}.question is required")
        aliases = field.get("aliases", [])
        if isinstance(aliases, str):
            aliases = [aliases]
        if not isinstance(aliases, list) or not all(
            isinstance(alias, str) and alias.strip() for alias in aliases
        ):
            errors.append(f"{label}.aliases must be a list of paths")


def has_content(value: Any) -> bool:
    if isinstance(value, str):
        return bool(value.strip())
    if isinstance(value, list):
        return any(has_content(item) for item in value)
    if isinstance(value, dict):
        return any(has_content(item) for item in value.values())
    return value is not None


def contains_placeholder(value: Any) -> bool:
    if isinstance(value, str):
        return bool(re.search(r"\bTODO\b|\{[^}]+\}", value, re.I))
    if isinstance(value, list):
        return any(contains_placeholder(item) for item in value)
    if isinstance(value, dict):
        return any(contains_placeholder(item) for item in value.values())
    return False


def validate_card_bundle(skill_root: Path, errors: list[str]) -> None:
    card_path = skill_root / "skill-card.yaml"
    card_doc_path = skill_root / "skill-card.md"
    cases_path = skill_root / "cases" / "cases.json"
    pricing_path = skill_root / "pricing-card.yaml"

    for path in (card_path, card_doc_path, cases_path, pricing_path):
        if not path.is_file():
            errors.append(f"{path}: required Skill trust-bundle file is missing")

    card = load_yaml(card_path, errors) if card_path.is_file() else None
    if card is not None:
        if card.get("schema") != CARD_STANDARD:
            errors.append(f"{card_path}: schema must be {CARD_STANDARD}")
        required = (
            "description", "owner", "license", "use_case", "deployment",
            "requirements", "risks", "references", "output", "version",
            "ethical_considerations", "dimensions", "pricing", "distribution",
        )
        for key in required:
            if key not in card or not has_content(card.get(key)):
                errors.append(f"{card_path}: required field '{key}' is missing or empty")
        dimensions = card.get("dimensions")
        if not isinstance(dimensions, list) or len(dimensions) < 3:
            errors.append(f"{card_path}: dimensions must contain at least three named dimensions")
        else:
            ids: set[str] = set()
            for index, dimension in enumerate(dimensions):
                label = f"{card_path}: dimensions[{index}]"
                if not isinstance(dimension, dict):
                    errors.append(f"{label}: expected a mapping")
                    continue
                dimension_id = compact_text(dimension.get("id"))
                if not dimension_id or dimension_id in ids:
                    errors.append(f"{label}: id is required and must be unique")
                ids.add(dimension_id)
                for key in ("label", "description", "evidence"):
                    if not compact_text(dimension.get(key)):
                        errors.append(f"{label}: '{key}' is required")
        risks = card.get("risks")
        if not isinstance(risks, list) or not risks:
            errors.append(f"{card_path}: risks must contain at least one risk and mitigation")
        else:
            for index, risk in enumerate(risks):
                if not isinstance(risk, dict) or not compact_text(risk.get("risk")) or not compact_text(risk.get("mitigation")):
                    errors.append(f"{card_path}: risks[{index}] needs risk and mitigation")
        distribution = card.get("distribution")
        if not isinstance(distribution, dict) or not isinstance(distribution.get("paid"), list) or not isinstance(distribution.get("free"), list):
            errors.append(f"{card_path}: distribution must declare paid and free lists")
        if contains_placeholder(card):
            errors.append(f"{card_path}: replace unresolved TODO or template placeholders")

    if card_doc_path.is_file():
        card_doc = read_text(card_doc_path)
        required_headings = (
            "Description", "Owner", "License", "Use Case", "Deployment Geography",
            "Requirements", "Known Risks", "References", "Skill Output",
            "Skill Version", "Ethical Considerations", "User Cases",
            "Dimension Map", "Pricing Basis", "Distribution",
        )
        for heading in required_headings:
            if not re.search(rf"(?mi)^#+\s+{re.escape(heading)}", card_doc):
                errors.append(f"{card_doc_path}: add the '{heading}' section")
        if re.search(r"\bTODO\b|\{[^}]+\}", card_doc, re.I):
            errors.append(f"{card_doc_path}: replace unresolved TODO or template placeholders")

    if cases_path.is_file():
        try:
            cases = json.loads(read_text(cases_path))
        except json.JSONDecodeError as exc:
            errors.append(f"{cases_path}: invalid JSON: {exc}")
            cases = []
        if not isinstance(cases, list) or not cases:
            errors.append(f"{cases_path}: include at least one real user case")
        else:
            for index, case in enumerate(cases):
                label = f"{cases_path}: cases[{index}]"
                if not isinstance(case, dict):
                    errors.append(f"{label}: expected a mapping")
                    continue
                for key in ("title", "description", "input", "prompt", "output"):
                    if not has_content(case.get(key)):
                        errors.append(f"{label}: '{key}' is required")
                if contains_placeholder(case):
                    errors.append(f"{label}: replace unresolved TODO or template placeholders")
                for image_key in ("cover", "gallery"):
                    image_values = case.get(image_key, [])
                    if isinstance(image_values, str):
                        image_values = [image_values]
                    if not isinstance(image_values, list):
                        errors.append(f"{label}: '{image_key}' must be a string or list")
                        continue
                    for image in image_values:
                        if not isinstance(image, str) or not image.strip():
                            errors.append(f"{label}: '{image_key}' contains an empty path")
                        elif not re.match(r"^(?:https?:|/|data:)", image) and not (skill_root / image).is_file():
                            errors.append(f"{label}: case asset does not exist: {image}")

    pricing = load_yaml(pricing_path, errors) if pricing_path.is_file() else None
    if pricing is not None:
        if pricing.get("schema") != PRICING_CARD_SCHEMA:
            errors.append(f"{pricing_path}: schema must be {PRICING_CARD_SCHEMA}")
        for key in ("model", "currency", "list_price_cny", "basis", "boundary", "review_trigger", "confidence"):
            if key not in pricing or (key != "list_price_cny" and not has_content(pricing.get(key))):
                errors.append(f"{pricing_path}: required field '{key}' is missing or empty")
        if contains_placeholder(pricing):
            errors.append(f"{pricing_path}: replace unresolved TODO or template placeholders")


def validate_composition_reference(skill_root: Path, errors: list[str]) -> None:
    path = skill_root / "references" / "skill-composition.md"
    if not path.is_file():
        errors.append(f"{path}: required Skill group composition record is missing")
        return
    text = read_text(path)
    required_headings = (
        "Nearby Skills Inspected",
        "Atomic Handoffs",
        "Overlap Decisions",
        "Composition Decision",
    )
    for heading in required_headings:
        if not re.search(rf"(?mi)^#+\s+{re.escape(heading)}", text):
            errors.append(f"{path}: add the '{heading}' section")
    if re.search(r"\bTODO\b|\{[^}]+\}", text, re.I):
        errors.append(f"{path}: replace unresolved TODO or template placeholders")


def validate_kit(root: Path, skill_names: set[str], errors: list[str]) -> None:
    manifest = root / "kit.yaml"
    if not manifest.exists():
        return
    data = load_yaml(manifest, errors)
    if data is None:
        return
    modules = data.get("modules")
    if not isinstance(modules, list) or not modules:
        errors.append(f"{manifest}: modules must be a non-empty list")
        return
    module_ids: set[str] = set()
    for index, module in enumerate(modules):
        label = f"{manifest}: modules[{index}]"
        if not isinstance(module, dict):
            errors.append(f"{label}: expected a mapping")
            continue
        module_id = compact_text(module.get("id"))
        skill_name = compact_text(module.get("skill"))
        relative = compact_text(module.get("path"))
        if not module_id or module_id in module_ids:
            errors.append(f"{label}: id is required and must be unique")
        module_ids.add(module_id)
        module_path = (root / relative).resolve()
        if (
            not relative
            or not is_relative_to(module_path, root.resolve())
            or not (module_path / "SKILL.md").is_file()
        ):
            errors.append(f"{label}: missing module at '{relative}/SKILL.md'")
        if skill_name not in skill_names:
            errors.append(f"{label}: unresolved child skill '{skill_name}'")
    pipelines = data.get("pipelines")
    if not isinstance(pipelines, dict) or not pipelines:
        errors.append(f"{manifest}: pipelines must be a non-empty mapping")
        return
    for pipeline, sequence in pipelines.items():
        if not isinstance(sequence, list) or not sequence:
            errors.append(f"{manifest}: pipeline '{pipeline}' must be a non-empty list")
            continue
        missing = [str(item) for item in sequence if item not in module_ids]
        if missing:
            errors.append(
                f"{manifest}: pipeline '{pipeline}' has unknown modules: "
                + ", ".join(missing)
            )


def validate_local_references(root: Path, errors: list[str]) -> None:
    for path in iter_files(root):
        if path.suffix.lower() != ".md":
            continue
        text = read_text(path)
        for raw in MARKDOWN_LINK_RE.findall(text):
            target = raw.strip().split(maxsplit=1)[0].strip("<>").split("#", 1)[0]
            if (
                not target
                or re.match(r"^[a-z][a-z0-9+.-]*:", target, re.I)
                or any(token in target for token in ("TODO", "{", "}"))
            ):
                continue
            if not (path.parent / target).resolve().exists():
                errors.append(f"{path}: broken local link '{target}'")
        skill_root = path.parent if path.name == "SKILL.md" else root
        for variable, target in SKILL_PATH_RE.findall(text):
            if "TODO" in target:
                continue
            base = skill_root if variable == "SKILL_DIR" else root
            resolved = (base / target.rstrip(".,;:)")).resolve()
            if not is_relative_to(resolved, root.resolve()) or not resolved.exists():
                errors.append(f"{path}: missing required resource '${variable}/{target}'")


def validate_hygiene(root: Path, errors: list[str]) -> None:
    private_path = re.compile(r"(?:/Users/[^/\s]+/|[A-Za-z]:\\\\Users\\\\[^\\\s]+\\\\)")
    for path in root.rglob("*"):
        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
            continue
        if path.name in JUNK_NAMES or path.suffix.lower() in JUNK_SUFFIXES:
            errors.append(f"{path}: generated/cache artifact must not ship")
    for path in iter_files(root):
        if path.suffix.lower() not in TEXT_SUFFIXES or path.name == "validate_skill.py":
            continue
        text = read_text(path)
        if private_path.search(text):
            errors.append(f"{path}: contains a private absolute user path")
        if path.name != "init_skill.py" and re.search(r"\bTODO\s*[:：]", text):
            errors.append(f"{path}: unresolved TODO placeholder")
    for relative in ("workbuddy", "scripts/build_workbuddy.py"):
        if (root / relative).exists():
            errors.append(
                f"{root / relative}: platform distribution artifacts belong to skill-publish"
            )


def validate_source(root: Path, errors: list[str]) -> None:
    root_skill = root / "SKILL.md"
    skill_files = [root_skill, *sorted((root / "skills").glob("*/SKILL.md"))]
    if not root_skill.is_file():
        errors.append(f"{root_skill}: file is required")
        return
    parsed: list[tuple[Path, dict[str, Any]]] = []
    for path in skill_files:
        data = validate_skill_file(path, errors)
        if data:
            parsed.append((path, data))
    names = {compact_text(data.get("name")) for _, data in parsed}
    if len(names) != len(parsed):
        errors.append(f"{root}: every embedded Skill must have a unique name")
    for path, data in parsed:
        metadata = data.get("metadata")
        if isinstance(metadata, dict) and metadata.get("card_standard") == CARD_STANDARD:
            validate_card_bundle(path.parent, errors)
        validate_composition_reference(path.parent, errors)
        validate_runtime_manifest(path.parent, compact_text(data.get("name")), errors)
    validate_kit(root, names, errors)

    readme = root / "README.md"
    if not readme.is_file():
        errors.append(f"{readme}: file is required")
    elif parsed:
        metadata = parsed[0][1].get("metadata")
        version = compact_text(metadata.get("version")) if isinstance(metadata, dict) else ""
        if version and f"version-{version}-" not in read_text(readme):
            errors.append(f"{readme}: version badge must match {version}")

    validate_hygiene(root, errors)
    validate_local_references(root, errors)


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("path", type=Path, help="Local Skill source directory")
    args = parser.parse_args()
    root = args.path.expanduser().resolve()
    if not root.is_dir():
        print(f"ERROR: directory does not exist: {root}", file=sys.stderr)
        return 2
    errors: list[str] = []
    validate_source(root, errors)
    if errors:
        print(f"FAILED: {len(errors)} issue(s)")
        for error in errors:
            print(f"- {error}")
        return 1
    print(f"PASSED: source validation ({root})")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())