spritegen-cli 0.1.0__py3-none-any.whl

spritegen/sheet.py

@@ -0,0 +1,370 @@
+"""Close a board of animation frames into one row of a sprite sheet.
+
+Absorbed from the `board_to_row.py` this grew out of. Three decisions in it are load-bearing,
+and each is a way the animation breaks if it is done the other way:
+
+1. **One grid and one palette over the whole board at once, never per frame.** Frame
+   by frame, each cell lands on its own grid and its own palette, and the animation
+   flickers.
+2. **Cells are cut by the declared grid, not by islands of alpha.** The board arrived
+   with equal cells; finding the figures by alpha would lose where each one sits inside
+   its cell, and where it sits *is* the movement.
+3. **One transform for the whole set.** Scale and offset come from the box that holds
+   every frame and apply equally to all of them. Anchoring each frame on its own would
+   push the rising frame back down and the walk would stand still.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+#: The default sheet cell, in pixels. A project with another one passes `--cell`.
+CELL = 166
+
+#: The GIF's flat backdrop. GIF has no partial alpha, and index transparency leaves a
+#: fringe around the figure, so the preview gets a solid ground instead.
+GIF_BACKDROP = (32, 32, 32, 255)
+
+#: The art directions a row can be closed in, and the subdirectory each one goes in.
+#: Pixel art is one of them and not the destination of every sprite — plenty of sprite
+#: art is a crisp raster with an anti-aliased edge, and `as-is` covers the case where
+#: the art arrived in the direction it was wanted in. See `board_to_row`.
+ART_DIRECTIONS = ("as-is", "sharp", "pixel-art")
+
+#: Below this the alpha is background smear, above it the alpha is the figure. Sprite
+#: art of this kind has a real anti-aliased edge — in the sheet this was measured
+#: against, 16% of a cell is partial alpha — so this is a floor and a ceiling rather
+#: than a threshold that would make the edge binary.
+ALPHA_FLOOR = 16
+ALPHA_CEIL = 240
+
+
+def parse_grid(text: str) -> tuple[int, int]:
+    """`3x2` to `(3, 2)`."""
+    try:
+        cols, rows = (int(value) for value in text.lower().split("x", 1))
+    except ValueError:
+        raise ValueError(f"a grid is COLSxROWS, e.g. 3x2; got {text!r}") from None
+    if cols < 1 or rows < 1:
+        raise ValueError(f"a grid needs positive sides; got {text!r}")
+    return cols, rows
+
+
+def pixelate_board(image, colors: int, seed: int | None = None):
+    """Recover the native grid of the whole board. Returns the image and what it found.
+
+    Seeded for the reason `imaging.to_pixelart` is: pixelfixer reconstructs by k-means on
+    OpenCV's global RNG, so without this two runs of one board differ.
+    """
+    from .imaging import PIXELART_SEED, require_pixelfixer
+
+    require_pixelfixer()
+
+    import cv2
+    import numpy as np
+    from PIL import Image
+    from pixelfixer import detect
+    from pixelfixer.reconstruct import reconstruct
+
+    cv2.setRNGSeed(PIXELART_SEED if seed is None else seed)
+    rgba = np.array(image.convert("RGBA"))
+    found = detect(rgba)
+    out = Image.fromarray(
+        reconstruct(rgba, found["step_x"], found["step_y"], found["cols"], found["rows"])
+    )
+    if colors:
+        out = quantise(out, colors)
+    return out, found
+
+
+def resize_rgba(image, size: tuple[int, int], filter_):
+    """Resize without letting the transparent pixels darken the edge.
+
+    A smooth filter weights a neighbour by distance and nothing else, and a fully
+    transparent pixel still carries an RGB — usually black, because that is what the
+    matte left behind it. Averaging that in is where the dark fringe around a shrunk
+    sprite comes from. Premultiplying makes a pixel's weight its own alpha, which is
+    what the average should have been all along.
+
+    `NEAREST` picks one pixel rather than averaging any, so it takes neither the fringe
+    nor this treatment, and goes straight through. That is also what keeps the integer
+    upscale path byte for byte what it was.
+    """
+    from PIL import Image
+
+    if filter_ == Image.NEAREST:
+        return image.resize(size, filter_)
+
+    import numpy as np
+
+    source = np.asarray(image.convert("RGBA"), dtype=np.float32)
+    weight = source[:, :, 3:4] / 255.0
+    premultiplied = np.concatenate([source[:, :, :3] * weight, source[:, :, 3:4]], axis=2)
+    small = Image.fromarray(premultiplied.round().astype(np.uint8), "RGBA").resize(size, filter_)
+
+    out = np.asarray(small, dtype=np.float32)
+    alpha = out[:, :, 3:4] / 255.0
+    straight = np.divide(
+        out[:, :, :3], alpha, out=np.zeros_like(out[:, :, :3]), where=alpha > 0
+    )
+    merged = np.concatenate([straight, out[:, :, 3:4]], axis=2)
+    return Image.fromarray(merged.round().clip(0, 255).astype(np.uint8), "RGBA")
+
+
+def fit_scale(span_w: int, span_h: int, cell_size: int, fit: bool = False) -> int | float:
+    """The largest scale at which the figure still fits the cell.
+
+    Integer while an integer fits, because a sprite enlarged by a whole factor keeps its
+    edges and one enlarged by 1.5 does not. Below one there is no such choice to make:
+    the art is bigger than the cell and the only question is by how much it comes down,
+    so the fraction is exact and the caller reduces with a smooth filter.
+
+    **`fit` is off by default, and that is not timidity.** Reducing is the half that was
+    missing — a sharp anchor generated at 1024 px overflows a 166 cell and `max(1, ...)`
+    left it there. But `board_to_row.py`'s output on a board that overflows is a parity
+    baseline, and quietly reducing where that script did not would break the one promise
+    the port makes. So the new behaviour arrives where the new route asks for it, and
+    the old route comes out byte for byte what it was.
+    """
+    integer = min(cell_size // span_w, cell_size // span_h)
+    if integer >= 1:
+        return integer
+    return min(cell_size / span_w, cell_size / span_h) if fit else 1
+
+
+def harden_alpha(image, floor: int = ALPHA_FLOOR, ceil: int = ALPHA_CEIL):
+    """Cut the smear off the alpha and snap the nearly-solid to solid.
+
+    Reducing a matted figure leaves a long faint tail where the matte's own uncertainty
+    was, and at cell size that tail reads as a halo. What it must not do is make the
+    edge binary: sprite art of this kind is anti-aliased, and a figure with a hard
+    outline does not sit beside one that has none.
+
+    So the band between `floor` and `ceil` is kept and stretched over the full range,
+    everything under `floor` goes to nothing, everything over `ceil` goes to solid.
+    """
+    import numpy as np
+    from PIL import Image
+
+    if floor >= ceil:
+        raise ValueError(f"the alpha floor {floor} is not below the ceiling {ceil}")
+
+    rgba = np.asarray(image.convert("RGBA")).copy()
+    alpha = rgba[:, :, 3].astype(np.float32)
+    stretched = (alpha - floor) * (255.0 / (ceil - floor))
+    rgba[:, :, 3] = stretched.clip(0, 255).round().astype(np.uint8)
+    return Image.fromarray(rgba, "RGBA")
+
+
+def quantise(image, colors: int):
+    """One palette over whatever it is given, alpha kept out of the vote.
+
+    No dither, for the reason `imaging.to_pixelart` gives: it scatters half-tone noise
+    across areas the reduction just made flat. Called on the assembled row rather than
+    on a cell, so all six frames share the palette and the sprite does not shift colour
+    as it walks.
+    """
+    from PIL import Image
+
+    quantized = image.convert("RGB").quantize(colors=colors, dither=Image.Dither.NONE)
+    merged = quantized.convert("RGBA")
+    merged.putalpha(image.getchannel("A"))
+    return merged
+
+
+def cut_cells(image, cols: int, rows: int, frames: int) -> list:
+    """Divide by the declared grid. The division remainder stays in the last cell."""
+    width, height = image.size
+    cell_w, cell_h = width / cols, height / rows
+    cells = []
+    for index in range(frames):
+        col, row = index % cols, index // cols
+        box = (
+            round(col * cell_w),
+            round(row * cell_h),
+            round((col + 1) * cell_w),
+            round((row + 1) * cell_h),
+        )
+        cells.append(image.crop(box))
+    return cells
+
+
+def union_bounds(cells: list) -> tuple[int, int, int, int]:
+    """The box holding the figure in every frame, in cell coordinates."""
+    boxes = [cell.getbbox() for cell in cells]
+    if any(box is None for box in boxes):
+        raise ValueError("a frame came out empty: check the grid and the frame count")
+    return (
+        min(box[0] for box in boxes),
+        min(box[1] for box in boxes),
+        max(box[2] for box in boxes),
+        max(box[3] for box in boxes),
+    )
+
+
+def build_row(
+    cells: list, scale: int | float | None, cell_size: int = CELL, fit: bool = False
+) -> tuple[list, dict]:
+    """Place every frame into a sheet cell under one shared transform.
+
+    The transform runs both ways. Enlarging is by a whole factor and by nearest
+    neighbour, which is what a sprite drawn small needs. Reducing is by the exact
+    fraction that fits and by a smooth filter, which is what a sharp anchor generated
+    at 1024 px needs — and it is the same one transform for every frame either way,
+    because scale and offset come from the box holding the whole set.
+
+    Reducing happens only under `fit`, or under a `scale` under one given outright. See
+    `fit_scale` for why the default leaves an overflow where it stands.
+    """
+    from PIL import Image
+
+    left, top, right, bottom = union_bounds(cells)
+    span_w, span_h = right - left, bottom - top
+    if scale is None:
+        scale = fit_scale(span_w, span_h, cell_size, fit)
+
+    shrinking = scale < 1
+    filter_ = Image.LANCZOS if shrinking else Image.NEAREST
+    scaled_w = max(1, round(span_w * scale))
+    scaled_h = max(1, round(span_h * scale))
+    # Centred across, feet on the cell floor: the anchor the client draws from.
+    off_x = (cell_size - scaled_w) // 2
+    off_y = cell_size - scaled_h
+
+    placed = []
+    for cell in cells:
+        crop = cell.crop((left, top, right, bottom))
+        sized = resize_rgba(crop, (scaled_w, scaled_h), filter_)
+        target = Image.new("RGBA", (cell_size, cell_size), (0, 0, 0, 0))
+        target.paste(sized, (off_x, off_y), sized)
+        placed.append(target)
+
+    return placed, {
+        "union": f"{span_w}x{span_h}",
+        "scale": int(scale) if float(scale).is_integer() else round(float(scale), 4),
+        "placed": f"{scaled_w}x{scaled_h}",
+        "offset": f"{off_x},{off_y}",
+        "overflow": scaled_w > cell_size or scaled_h > cell_size,
+    }
+
+
+def write_gif(placed: list, path: Path, fps: int = 7) -> Path:
+    """A looping preview of the row, on a flat backdrop."""
+    from PIL import Image
+
+    flat = []
+    for frame in placed:
+        back = Image.new("RGBA", frame.size, GIF_BACKDROP)
+        back.paste(frame, (0, 0), frame)
+        flat.append(back.convert("P", palette=Image.Palette.ADAPTIVE))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    flat[0].save(path, save_all=True, append_images=flat[1:], duration=round(1000 / fps), loop=0)
+    return path
+
+
+def board_to_row(
+    source: Path,
+    out: Path,
+    *,
+    grid: tuple[int, int],
+    frames: int | None = None,
+    cell: int = CELL,
+    scale: int | float | None = None,
+    fit: bool = False,
+    art: str = "as-is",
+    colors: int = 0,
+    alpha_floor: int = ALPHA_FLOOR,
+    alpha_ceil: int = ALPHA_CEIL,
+    chroma: str | None = None,
+    tol: float = 60.0,
+    feather: float = 24.0,
+    chroma_mode: str = "flood",
+    gif: Path | None = None,
+    fps: int = 7,
+) -> dict:
+    """A whole board through to one row of the sheet. Returns what it measured.
+
+    `chroma` cuts the key off the whole board at once, before anything is divided. The
+    same tolerance and the same flood then apply to all six cells, so every edge comes
+    out alike; done cell by cell the contour alpha varies between frames and the
+    silhouette flickers.
+
+    `art` is the direction the row is closed in. The three are not settings of one
+    thing, and none of them is the default the others fall back to:
+
+    - **`pixel-art`** recovers a native grid the art already has, through `pixelfixer`,
+      and rewrites the board on it before anything is divided. It needs blocks to find:
+      on a smooth render the vote returns nonsense, which is why the report carries
+      `native` — that number is how you check a grid was there at all.
+    - **`sharp`** assumes there is no grid, because plenty of sprite art has none. The
+      reduction into the cell *is* the resolution decision, so all this adds afterwards
+      is the alpha treatment and, where asked, one palette — over the assembled row, so
+      the frames cannot drift apart.
+    - **`as-is`** does neither, for art that already arrived in the direction it was
+      wanted in.
+
+    A sprite can be closed in more than one of them, and each goes in its own directory
+    under `sheet/`. Which one a project ships is the project's decision, not this
+    function's.
+    """
+    from PIL import Image
+
+    cols, rows = grid
+    frames = frames or cols * rows
+    if frames > cols * rows:
+        raise ValueError(f"{frames} frames do not fit a {cols}x{rows} grid")
+    if art not in ART_DIRECTIONS:
+        raise ValueError(f"art is one of {', '.join(ART_DIRECTIONS)}; got {art!r}")
+    if colors and art == "as-is":
+        raise ValueError("colors needs an art direction to quantise into")
+
+    cut_report = None
+    if chroma:
+        from .imaging import cut_chroma, parse_chroma
+
+        out.parent.mkdir(parents=True, exist_ok=True)
+        cut = out.with_name(f"{out.stem}.cut.png")
+        cut.write_bytes(source.read_bytes())
+        cut_report = cut_chroma(cut, parse_chroma(chroma), tol, feather, True, 2, chroma_mode)
+        source = cut
+
+    board = Image.open(source).convert("RGBA")
+    native = None
+    if art == "pixel-art":
+        board, found = pixelate_board(board, colors)
+        native = f"{found['cols']}x{found['rows']}"
+
+    cells = cut_cells(board, cols, rows, frames)
+    # `sharp` lands the art on the cell, so a figure larger than the cell is the
+    # ordinary case there rather than a mistake, and it comes down without being asked.
+    placed, report = build_row(cells, scale, cell, fit or art == "sharp")
+
+    strip = Image.new("RGBA", (cell * len(placed), cell), (0, 0, 0, 0))
+    for index, frame in enumerate(placed):
+        strip.paste(frame, (index * cell, 0), frame)
+
+    if art == "sharp":
+        # On the whole strip and not on a cell: one palette and one alpha decision for
+        # every frame, which is the same reason `detect` runs before the board is cut.
+        strip = harden_alpha(strip, alpha_floor, alpha_ceil)
+        if colors:
+            strip = quantise(strip, colors)
+        placed = [
+            strip.crop((index * cell, 0, (index + 1) * cell, cell))
+            for index in range(len(placed))
+        ]
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    strip.save(out)
+
+    if gif:
+        write_gif(placed, gif, fps)
+
+    return {
+        **report,
+        "art": art,
+        "native": native,
+        "frames": len(placed),
+        "cell": cell,
+        "chroma": cut_report,
+    }

spritegen/skill/__init__.py

@@ -0,0 +1,303 @@
+"""The Claude skill this CLI writes for itself — R5.1, R5.2.
+
+One file goes out, `.claude/skills/spritegen/SKILL.md`, and it is the whole skill: how to
+run the tool, the flow a character goes through, the prompt skeletons, and every option of
+every stage. A skill is read by an agent that has the file and nothing else, so splitting
+it across a reference tree buys nothing here and costs a reader who has to guess which
+part holds the answer.
+
+The file is half authored and half generated. The prose is shipped beside this module in
+`files/SKILL.md`, which carries marker lines; each marker is replaced with a table read
+out of `stages.STAGES` and `endpoints.MOTION`.
+
+That split is the whole point of the command. A skill describing the stages in prose is a
+second copy of the registry, and the copy is the one that goes stale: the CLI gains an
+option, the skill keeps offering the old one, and whoever reads it spends money on a call
+the parser rejects. What the registry knows is generated. What it cannot know — why the
+anchor faces south, why `motion` is preferred over `video` — is prose, and stays prose.
+
+A marker the source lost is an error rather than a silent omission: the skill would
+otherwise ship describing no stages at all.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib import resources
+from pathlib import Path
+
+from .. import endpoints
+from .. import stages as registry
+
+#: Where the skill goes, under whichever `.claude` was found.
+SKILL_DIR = Path(".claude") / "skills" / "spritegen"
+
+#: The one file. `files/SKILL.md` beside this module is its source.
+SKILL_FILE = "SKILL.md"
+
+_STAMP = (
+    "<!-- Generated by `spritegen init`. Edit the source in the spritegen\n"
+    "     repository, at src/spritegen/skill/files/SKILL.md, not this copy:\n"
+    "     `init --force` rewrites it. -->"
+)
+
+
+def _stamp(text: str) -> str:
+    """`text` with the generated-by note in it, under the frontmatter — R5.5.
+
+    Injected rather than authored into the source, so it cannot be edited away by
+    accident. A YAML block has to stay the first thing in the file, so the note goes
+    beneath it.
+    """
+    if text.startswith("---\n"):
+        end = text.find("\n---\n", 4)
+        if end != -1:
+            cut = end + len("\n---\n")
+            return f"{text[:cut]}\n{_STAMP}\n{text[cut:]}"
+    return f"{_STAMP}\n\n{text}"
+
+
+def _source() -> str:
+    """The authored half, read out of the package rather than off a path.
+
+    It travels inside the wheel, so an installed spritegen writes the same skill as one
+    run from a checkout.
+    """
+    return resources.files(__package__).joinpath("files", SKILL_FILE).read_text(encoding="utf-8")
+
+
+def _takes(option: registry.Option) -> str:
+    """What one option accepts, as a reader needs it rather than as argparse sees it."""
+    if option.action == "store_true":
+        return "flag"
+    if option.choices:
+        return " / ".join(f"`{value}`" for value in option.choices)
+    if option.action == "append":
+        return f"`{option.kind}`, repeatable"
+    return f"`{option.kind}`"
+
+
+def _default(option: registry.Option) -> str:
+    """That option's default. A `0` is kept rather than shown as absent: several of them
+    mean *the whole of it* — every cell of the row, the largest scale that fits."""
+    if option.action == "store_true":
+        return "off"
+    if option.default is None or option.default == "":
+        return "-"
+    return f"`{option.default}`"
+
+
+def stage_table() -> str:
+    """The pipeline as one table — what each stage needs, writes, and whether it spends."""
+    rows = ["| Stage | Needs | Writes | Spends |", "|---|---|---|---|"]
+    for stage in registry.STAGES:
+        needs = " or ".join(f"`{name}`" for name in stage.requires) if stage.requires else "-"
+        spends = "yes" if stage.paid else "no"
+        rows.append(f"| `{stage.name}` | {needs} | `{stage.produces}/` | {spends} |")
+    return "\n".join(rows)
+
+
+def option_table(stage: registry.Stage) -> str:
+    """Every option that stage declares."""
+    if not stage.options:
+        return "No options of its own."
+    rows = ["| Option | Takes | Default | What it does |", "|---|---|---|---|"]
+    for option in stage.options:
+        flags = ", ".join(f"`{flag}`" for flag in option.flags)
+        help_text = option.help.replace("|", r"\|")
+        rows.append(f"| {flags} | {_takes(option)} | {_default(option)} | {help_text} |")
+    return "\n".join(rows)
+
+
+def stage_sections() -> str:
+    """One section per stage: what it needs, what it writes, what it costs, its options."""
+    parts = []
+    for stage in registry.STAGES:
+        needs = " or ".join(f"`{name}`" for name in stage.requires) if stage.requires else "nothing"
+        cost = "spends money" if stage.paid else "free, and free to re-run"
+        parts += [
+            f"## `spritegen {stage.name} <asset>`",
+            "",
+            f"{stage.summary[:1].upper()}{stage.summary[1:]}. Needs {needs}, "
+            f"writes `{stage.produces}/`, {cost}.",
+            "",
+            option_table(stage),
+            "",
+        ]
+    parts.append(
+        "Every stage also takes `--force`, to rewrite output it already produced, and every"
+        "\npaid one takes `--dry-run`."
+    )
+    return "\n".join(parts)
+
+
+def endpoint_table() -> str:
+    """The motion endpoints and what each one takes through `--set`.
+
+    Generated for the same reason the stages are: `--set` is checked against this schema
+    before anything is spent, so a skill quoting a stale copy of it walks the operator
+    into a rejection they pay a round trip to find out about.
+    """
+    lines = [
+        "## The `motion` endpoints",
+        "",
+        "`--set NAME=VALUE` is checked against the chosen endpoint before the call is built,"
+        " so\nan option this table does not list is refused rather than paid for.",
+        "",
+    ]
+    for name, endpoint in endpoints.MOTION.items():
+        default = " (the default)" if name == endpoints.DEFAULT else ""
+        lines += [f"**`--endpoint {name}`**{default} — `{endpoint.id}`", "", endpoint.summary, ""]
+        if not endpoint.options:
+            lines += ["Takes no option of its own.", ""]
+            continue
+        lines += ["| `--set` | Accepts | Sent unless overridden |", "|---|---|---|"]
+        for option, allowed in sorted(endpoint.options.items()):
+            takes = " / ".join(f"`{value}`" for value in allowed) if allowed else "any"
+            sent = endpoint.defaults.get(option)
+            lines.append(f"| `{option}` | {takes} | {'-' if sent is None else f'`{sent}`'} |")
+        lines.append("")
+    return "\n".join(lines).rstrip("\n")
+
+
+_FREE = """## The commands that spend nothing
+
+| Command | What it does |
+|---|---|
+| `spritegen new <asset>` | open an asset directory; refuses one that already exists |
+| `spritegen status` | every asset, the stage that completed last, the ones that could run now |
+| `spritegen cost [<asset>]` | the paid calls, read from the ledger alone |
+| `spritegen init [--dir <path>] [--force]` | rewrite this skill |"""
+
+
+def free_commands() -> str:
+    """The commands that are not stages. Authored, because the registry does not hold them."""
+    return _FREE
+
+
+#: Each marker in the source, and what replaces it. All four are required — see `render`.
+SECTIONS: dict[str, object] = {
+    "<!-- generated: stages -->": stage_table,
+    "<!-- generated: options -->": stage_sections,
+    "<!-- generated: endpoints -->": endpoint_table,
+    "<!-- generated: free -->": free_commands,
+}
+
+
+def render() -> str:
+    """`SKILL.md`, whole — R5.1, R5.2, R5.5."""
+    text = _source()
+    for marker, section in SECTIONS.items():
+        if marker not in text:
+            raise ValueError(
+                f"{SKILL_FILE} lost its {marker} line; it would ship with that section missing"
+            )
+        text = text.replace(marker, section())
+    return _stamp(text)
+
+
+def _found_claude(start: Path) -> Path | None:
+    """The nearest directory at or above `start` that already holds a `.claude`."""
+    for base in (start, *start.parents):
+        if (base / ".claude").is_dir():
+            return base
+    return None
+
+
+def target(directory: str | Path | None = None, start: Path | None = None) -> Path:
+    """The directory the skill goes in — R5.4, R5.6.
+
+    A named directory wins. Without one, the working directory and each of its parents are
+    searched for an existing `.claude`, the same way `cli.load_env` searches for a `.env`
+    and for the same reason: this tool is run from inside `spritegen/`, while the checkout
+    that wants the skill is the one above it.
+
+    With no `.claude` anywhere it refuses rather than creating one. A `.claude` is how a
+    workspace says it is a workspace, and a skill written into a directory that never had
+    one is a file nothing reads — `--dir` is the way to say where, when the answer is not
+    a workspace already there.
+
+    The search does not stop at the home directory, so run from a checkout with no
+    `.claude` of its own it finds the user's `~/.claude` and writes a skill available to
+    every project. The command prints where it wrote, so that is visible rather than
+    silent.
+    """
+    if directory:
+        return Path(directory)
+    start = Path.cwd() if start is None else start
+    found = _found_claude(start)
+    if found is None:
+        raise FileNotFoundError(
+            f"no .claude directory at {start} or above it; name one with --dir"
+        )
+    return found / SKILL_DIR
+
+
+def write(root: Path, *, force: bool = False) -> Path:
+    """Write the skill under `root` — R5.1, R5.3."""
+    text = render()
+    path = root / SKILL_FILE
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} is already there; pass --force to rewrite it")
+    root.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def _confirm(question: str, assume_yes: bool) -> bool:
+    """Ask on a terminal, and take silence for no anywhere else.
+
+    `init` writes into somebody else's project, so it asks first. What it must not do is
+    block: run from a script, a hook or a harness there is nobody at the other end, and a
+    prompt that never returns is worse than a step that did not happen. So a
+    non-interactive stdin is a no, and `--yes` is how such a run says yes in advance.
+    """
+    if assume_yes:
+        return True
+    if not sys.stdin.isatty():
+        print(f"{question} [skipped: nothing is attached to answer; pass --yes]")
+        return False
+    return input(f"{question} [y/N] ").strip().lower() in {"y", "yes"}
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Set the project up: the asset workspace, and the skill — R5.1.
+
+    Two acts, and only the first is unconditional. The workspace is this tool's own
+    directory and nothing else reads it, so it is made without asking. The skill goes
+    into the project's `.claude`, which belongs to whoever works there, so it is asked
+    for — see `_confirm` for what happens when there is nobody to ask.
+
+    ASCII only, for the reason `workspace.cmd_status` is: a Windows console on a codepage
+    without an em dash drops the line rather than raising where anyone would see it.
+    """
+    from .. import workspace
+
+    assume_yes = getattr(args, "yes", False)
+    force = getattr(args, "force", False)
+
+    root = workspace.assets_root()
+    if root.is_dir():
+        print(f"workspace already at {root}")
+    else:
+        root.mkdir(parents=True)
+        print(f"workspace created at {root}")
+
+    try:
+        destination = target(getattr(args, "directory", None))
+    except FileNotFoundError:
+        # No .claude anywhere. Offer the project root rather than refusing outright:
+        # this is setup, and a project without one is the ordinary case for setup. A
+        # declined offer is still the refusal it always was, and still exits 1 — what
+        # changed is that there is now an offer to decline.
+        where = workspace.project_root() / SKILL_DIR
+        if not _confirm(f"no .claude found; install the skill at {where}?", assume_yes):
+            raise
+        destination = where
+
+    # `write` refuses a skill already there, and that refusal is the exit code the CLI
+    # reports. Checking it here as well would answer twice and disagree once.
+    path = write(destination, force=force)
+    print(f"skill written to {path}  ({len(path.read_text(encoding='utf-8').splitlines())} lines)")
+    return 0