@skaile/workspaces 0.25.0 → 0.27.0

package/dist/factory-assets/skills/authoring-skaile-manifests/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: authoring-skaile-manifests
+description: "Use when creating or fixing a skaile.yaml manifest for a new or existing skill / asset / MCP-server repo so it works with @skaile/workspaces and stores. Covers the publication half (publisher, version, assets[]), the consumption half (sources, stores, dependencies, overrides), the canonical dependency-ref grammar (kind:@publisher/name#version), the version waterfall, conflict resolution, and the v3 lock file. Also use to generate a manifest from an existing tree or migrate a legacy manifest."
+metadata:
+  version: '0.1.0'
+  stage: alpha
+  tags:
+    - skaile
+    - workspaces
+    - manifest
+    - skaile.yaml
+    - dependencies
+    - mcp
+    - migrate
+    - lockfile
+---
+
+# Authoring `skaile.yaml` manifests
+
+You are creating or repairing a `skaile.yaml` so a repo (skills, assets, or an
+MCP server) resolves through `@skaile/workspaces` and any store. This skill owns
+the manifest and the **latest dependency standard**. For file layout and asset
+content, see **[authoring-skaile-assets]**.
+
+Reference (canonical): the in-repo concept doc `docs/concepts/manifest-schema.md`
+and the spec `_devlog/specs/2026-05-31-manifest-canonical-identity.md`.
+The full dependency standard is in
+[`references/dependency-standard.md`](./references/dependency-standard.md).
+
+## One file, two halves
+
+`skaile.yaml` lives at the repo root. A repo can be **source-only** (publication
+half), **project-only** (consumption half), or both.
+
+### Publication half — "this repo IS a source"
+
+```yaml
+publisher: skaile-ai            # optional; defaults to the source URL's GitHub org/user
+version: 1.4.0                  # optional; see Version waterfall
+
+assets:                         # optional; when present it EXHAUSTIVELY lists publishable assets
+  - kind: skill
+    name: audit
+    root: skills/audit          # recursive walk: every file under root joins the asset
+  - kind: bundle
+    name: skaile-development
+    root: bundles/skaile-development
+    version: 2.0.0              # per-asset override of the source version
+  - kind: skill
+    name: composite-skill
+    files:                      # explicit listing; supports fast-glob globs
+      - SKILL.md
+      - scripts/*.py
+      - references/audit-rules.md
+  - kind: mcp-server
+    name: excel
+    root: mcp-servers/excel
+    publisher: vendor-x         # per-asset publisher: curator/mirror preserves original identity
+```
+
+- **`publisher`** — canonical, GitHub-shaped: ≤39 chars, alphanumeric + single
+  hyphens, no leading/trailing or double hyphen. Inherited from the source URL's
+  GitHub `<org-or-user>` when omitted. **Non-GitHub URLs (GitLab, self-hosted,
+  tarball) MUST set `publisher:` explicitly** — auto-derivation fails closed.
+- **`assets[]`** — `{kind, name, root?|files?, version?, publisher?}`. `root:`
+  walks a directory recursively; `files:` lists explicit paths/globs.
+- A content `name:` (e.g. `SKILL.md`) **MUST equal** its `assets[].name` — else
+  an index-time hard error. `metadata.version` in content is ignored.
+
+> ⚠️ **Exhaustive-list footgun.** A **non-empty `assets:` is the complete set of
+> resolvable assets.** Anything on disk but not listed is still browsable in
+> `skaile manage` (the browse scan walks files) yet **fails at install** with
+> `Asset not found`. When you add an agent/flow/skill to the tree, add it here
+> too — or omit `assets:` entirely and let the convention walker find everything.
+
+### Consumption half — "this repo IS a project"
+
+```yaml
+sources:                        # absent → no direct git resolution
+  - url: https://github.com/skaile-ai/ai-assets
+    pin: v1.4.0                 # optional: branch | tag | 40-char sha; defaults to default-branch HEAD
+
+stores:                         # absent → no catalog fallback
+  - url: https://skaile.store
+
+dependencies:                   # canonical refs only (grammar below)
+  - bundle:@skaile-ai/skaile-development#^2.0
+  - skill:@skaile-ai/use-exa#~1.0
+  - mcp:@skaile-ai/excel
+
+overrides:                      # conflict resolution; reason: is REQUIRED
+  - ref: skill:@skaile-ai/audit#1.4.0
+    source: https://github.com/skaile-ai/ai-assets
+    reason: "vendored patch for issue #42; revert when upstream merges"
+```
+
+- `sources[]` is `{url, pin?}` **only** — no `name`, `publisher`, or `branch`;
+  the cache slug is derived from the URL.
+- `stores[]` is `{url}` only.
+- `overrides[]` is `{ref, source, reason}`; an empty/missing `reason:` is a parse
+  error.
+- Legacy top-level keys `repositories:` and `ai_resources:` are **rejected at
+  parse time** — see Migration.
+
+## The latest dependency standard (canonical-identity, 2026-05-31)
+
+```
+kind:@<publisher>/name[#version]
+```
+
+`@` is the **scope sigil**, `#` the **version sigil** — `@publisher/name` reads
+like an npm scoped package. `<publisher>` is canonical, global, GitHub-shaped,
+and **required**; there is no project-local alias. `mcp:` is shorthand for
+`mcp-server:`. The lock key is a fully-pinned ref of exactly this shape
+(`kind:@<publisher>/name#version`).
+
+```
+skill:@skaile-ai/audit              # resolver picks highest SemVer candidate
+skill:@skaile-ai/audit#^1.4.0       # caret range
+bundle:@skaile-ai/skaile-development#~2.0
+mcp:@skaile-ai/excel                # = mcp-server:@skaile-ai/excel
+agent:@skaile-ai/reviewer#6a5266fdda9d1c697f537968532691f6d70c779a   # exact commit SHA
+```
+
+| Pin form | Meaning |
+|---|---|
+| `#1.4.0` | exact SemVer |
+| `#^1.4.0`, `#^1` | caret range |
+| `#~1.4.0`, `#~1.4` | tilde range |
+| `#1.x`, `#1.4.x` | wildcard |
+| `#<40-char-sha>` | exact source-commit pin |
+| absent | highest SemVer-sorted candidate |
+| `#main`, `#latest`, `#HEAD`, any floating ref | **parse-time error** |
+
+> 🛑 **The legacy `kind:name@<publisher>` grammar is GONE.** As of the
+> "remove legacy asset-ref aliases" change it is a **hard error**
+> (`publisher required in asset ref "…" — use kind:@<publisher>/name`), not a
+> deprecation warning. The older docs that mention a one-release grace period are
+> stale. Convert every ref and run the `migrate-skaile-manifest` skill on legacy
+> manifests.
+
+**`requires:` (content) is different and stays bare** — `kind:name`, no
+publisher, resolved within the same source. Only **bundle `dependencies:`** and
+**project `dependencies:`** use the full canonical grammar above. See
+[references/dependency-standard.md](./references/dependency-standard.md) for the
+complete rules, SHA-synthetic versions, and worked examples.
+
+## Version waterfall
+
+The version for an asset is the first of:
+
+1. `assets[].version` (per-asset in the source `skaile.yaml`).
+2. The source's top-level `version:`.
+3. A SemVer-shaped git tag (`git describe --tags`), `v` stripped.
+4. Synthetic `0.0.0-sha.<7char>` from the resolved commit.
+
+SHA-synthetic versions resolve only against their **exact literal** pin or the
+commit-SHA pin that minted them — never caret/tilde/wildcard. To get clean
+ranged installs, **tag your releases**.
+
+## Resolution + conflict detection (what authors must anticipate)
+
+The resolver gathers candidates per dep across every source clone and every store,
+filters by the pin, and picks the highest matching version. If two candidates for
+the same `(publisher, kind, name, version)` disagree on content `sha256`, it is a
+**hard error** with a dep-chain walk — unless an `overrides[]` entry pins one
+source (with a `reason:`). When a source and a store both produce the chosen
+version, a `catalog.getCanonicalDigest` probe cross-checks their `sha256`.
+
+Implication for authors: **never republish the same `(publisher, kind, name,
+version)` with different bytes.** Bump the version instead. Same coordinates must
+mean identical content everywhere, or every downstream consumer breaks.
+
+## Generate a manifest from an existing repo
+
+For a new or existing skill/asset/MCP repo with no (or a stale) `skaile.yaml`:
+
+1. **Enumerate assets on disk** — find every manifest file:
+   ```bash
+   find . \( -name SKILL.md -o -name AGENT.md -o -name agent.yaml \
+     -o -name CONTRACT.md -o -name MCP.md -o -name CONNECTOR.md \
+     -o -name knowledge.yaml -o -name '*.prompt.md' \
+     -o -name '*.flow.yaml' -o -name '*.flow.json' -o -name '*.bundle.yaml' \) \
+     -not -path '*/node_modules/*' -not -path '*/.git/*'
+   ```
+2. **Read each `name:`** (frontmatter or `name:`/`id:` field). For a single-file
+   asset use `files:`; for a directory-scoped asset (skill/agent/contract/
+   mcp-server/connector/knowledge) use `root:` at its directory.
+3. **Set `publisher:`** = the GitHub org if hosted there, else declare it.
+4. **Set `version:`** or rely on git tags.
+5. **Cross-check the count**: the number of `assets:` entries MUST equal the
+   number of manifest files found in step 1. A mismatch = the footgun. (This is
+   exactly the `assets:`-list-incomplete class of `Asset not found` bug.)
+6. **For an MCP repo specifically**: each server is an `MCP.md` with frontmatter
+   carrying runtime defaults (`transport`, `command`, `args`, `env`, `url`,
+   `headers`). Those land on the catalog entry's `metadata` so a consumer can
+   `dependencies: [mcp:@<pub>/<name>]` and get a working server with no inline
+   config. List each as `kind: mcp-server`.
+7. **Verify**: register the repo as a source in a scratch project and run
+   `skaile manage` + `skaile add` for a sampling of every kind (see
+   [authoring-skaile-assets] § Test a source locally).
+
+## v3 lock file (`skaile.lock.yaml`)
+
+Generated by `skaile install`; do not hand-edit. Keyed by canonical refs.
+
+```yaml
+locked_at: 2026-05-31T14:30:00Z
+schema_version: 3
+assets:
+  skill:@skaile-ai/audit#1.4.0:
+    sha256: 1da6294a...
+    source: { url: https://github.com/skaile-ai/ai-assets, commit: 6a5266fd... }
+    files:
+      - { path: skills/audit/SKILL.md, sha256: ... }
+    override_applied: false
+sources:
+  - { url: https://github.com/skaile-ai/ai-assets, commit: 6a5266fd... }
+```
+
+Old v1 lockfiles (`lockfile_version: 1`, `repositories:`) are rejected on read —
+regenerate with `rm skaile.lock.yaml && skaile install`.
+
+## Migration
+
+There is no `skaile manifest migrate` command. The transform
+(`repositories:`/`ai_resources:` → `sources:`/`dependencies:`, bare deps →
+`@<publisher>`, `@skaile` → `@skaile-ai` rebrand, legacy `kind:name@pub` →
+`kind:@pub/name`) is done by the **`migrate-skaile-manifest`** skill. Run it from
+an AI session against each legacy `skaile.yaml`.
+
+## Manifest checklist
+
+- [ ] `publisher:` set (or auto-derivable from a GitHub URL).
+- [ ] Every manifest file on disk has a matching `assets:` entry (or `assets:` omitted).
+- [ ] Each content `name:` equals its `assets[].name`.
+- [ ] Every `dependencies:`/bundle ref uses `kind:@publisher/name[#version]` — no legacy `@pub` suffix.
+- [ ] Pins are SemVer/SHA — no `main`/`latest`/`HEAD`.
+- [ ] Released versions are git-tagged so ranges resolve.
+- [ ] `overrides[]` (if any) carry a non-empty `reason:`.
+- [ ] `skaile add` succeeds for a sample of every kind in a scratch project.
+
+[authoring-skaile-assets]: ../authoring-skaile-assets/SKILL.md

package/dist/factory-assets/skills/authoring-skaile-manifests/references/dependency-standard.md

@@ -0,0 +1,197 @@
+# The skaile dependency standard (canonical-identity)
+
+Deep reference for the dependency grammar used by `@skaile/workspaces`. The
+authoritative source is `docs/concepts/manifest-schema.md` and the spec
+`_devlog/specs/2026-05-31-manifest-canonical-identity.md` (scoped-grammar follow-up:
+`_devlog/specs/2026-06-02-scoped-asset-ref-grammar.md`). This file restates it for
+asset authors and flags where the current code is **stricter than the older docs**.
+
+## 1. Identity
+
+Every asset has a global identity tuple:
+
+```
+(publisher, kind, name, version)
+```
+
+- **Asset-intrinsic.** Declared in the *source's* `skaile.yaml`, never by the
+  consuming project. There is no project-local renaming.
+- **publisher** — canonical, GitHub-shaped: 1–39 chars, alphanumeric + single
+  hyphens, no leading/trailing hyphen, no double hyphen. Auto-derived from a
+  GitHub source URL's org/user; **must be declared** for any non-GitHub URL.
+- **kind** — one of: `skill`, `agent`, `prompt`, `bundle`, `flow`, `contract`,
+  `mcp-server`, `persona`, `ruleset`, `knowledge`, `connector`.
+- **version** — SemVer (see § Version waterfall). Two assets with the same tuple
+  MUST be byte-identical.
+
+## 2. The canonical reference grammar
+
+```
+kind:@<publisher>/name[#version]
+```
+
+| Token | Role |
+|---|---|
+| `kind:` | asset kind + colon. `mcp:` is shorthand for `mcp-server:`. |
+| `@` | **scope sigil** — introduces the publisher, npm-style. |
+| `<publisher>/` | publisher namespace + slash. |
+| `name` | asset name. Permissive: anything except `/`, `#`, whitespace. |
+| `#version` | optional **version sigil** + pin. |
+
+Reads as an npm scoped package: `@skaile-ai/audit`.
+
+### Examples
+
+```
+skill:@skaile-ai/audit
+skill:@skaile-ai/audit#^1.4.0
+bundle:@skaile-ai/skaile-development#~2.0
+agent:@vercel-labs/reviewer
+mcp:@skaile-ai/excel                  # == mcp-server:@skaile-ai/excel
+contract:@skaile-ai/implementation-contract#1.0.0
+skill:@skaile-ai/audit#6a5266fdda9d1c697f537968532691f6d70c779a   # 40-char SHA pin
+```
+
+## 3. Pins
+
+| Pin form | Meaning |
+|---|---|
+| `#1.4.0` | exact SemVer |
+| `#^1.4.0`, `#^1` | caret range |
+| `#~1.4.0`, `#~1.4` | tilde range |
+| `#1.x`, `#1.4.x` | wildcard |
+| `#<40-char-sha>` | exact source-commit pin |
+| absent | resolver picks the highest SemVer-sorted candidate |
+| `#main`, `#latest`, `#HEAD`, any floating ref | **parse-time error** |
+
+Floating refs are rejected by design — resolution must be reproducible.
+
+## 4. SHA-synthetic versions
+
+When no version can be derived (no `assets[].version`, no source `version:`, no
+SemVer git tag), the resolver mints `0.0.0-sha.<7char>` from the commit. These:
+
+- participate in resolution,
+- satisfy **only** their exact literal pin (`#0.0.0-sha.abc1234`) or the
+  commit-SHA pin that produced them,
+- never match caret/tilde/wildcard ranges.
+
+Consequence: an untagged source resolves only when pinned exactly. **Tag
+releases** to enable ranged (`^`, `~`, `x`) installs.
+
+## 5. `requires:` vs `dependencies:` — the split that trips authors
+
+There are two distinct dependency channels. They use **different grammars**.
+
+### `requires:` — content frontmatter, intra-source, bare `kind:name`
+
+In a `SKILL.md` / `agent.yaml` / `MCP.md`, `requires:` lists peer assets the
+asset needs. Form is **`kind:name`** — no `@publisher`, no `#version`. The
+publisher is **inherited from the same source** (same-source assumption).
+
+```yaml
+# SKILL.md frontmatter
+metadata:
+  requires:
+    - contract:implementation-contract
+    - skill:use-exa
+```
+
+Accepted as a comma-separated string or a YAML list. Read from either the
+top level or under `metadata:`.
+
+### `dependencies:` — bundle & project manifests, full canonical refs
+
+A **bundle** (`*.bundle.yaml`) and a **project** `skaile.yaml` use
+`dependencies:` with the **full canonical grammar** and can cross publishers and
+pin versions:
+
+```yaml
+# a bundle, or a project skaile.yaml
+dependencies:
+  - skill:@skaile-ai/audit#^1.4
+  - agent:@skaile-ai/impl-build-implement
+  - skill:@vercel-labs/agent-skills
+```
+
+> Putting a full canonical ref in a content `requires:` (or a bare `kind:name`
+> in a project `dependencies:`) is the most common authoring mistake. Keep them
+> in their lanes: **`requires:` = bare same-source; `dependencies:` = canonical
+> cross-source.**
+
+### Transitive expansion
+
+Installing a bundle resolves every `dependencies:` ref, recursing into nested
+bundles to arbitrary depth. A shared dep is de-duped; cycles are broken by a
+`seen` set. A bare transitive ref inherits its parent candidate's publisher.
+
+## 6. Resolution algorithm (per dep)
+
+1. Gather **source candidates** from every cloned `sources[]` repo (provenance
+   index, keyed `<publisher>/<kind>:<name>`).
+2. Optionally gather **store candidates** from every `stores[]` catalog.
+3. Filter by the pin (SemVer range / SHA / exact).
+4. Pick the **highest** matching version.
+5. **Conflict check:** if ≥2 finalists at that version have divergent content
+   `sha256`, raise `CanonicalRefConflictError` with the dep chain — unless an
+   `overrides[]` entry selects one source.
+6. Cross-check: when a source and a store both produced the chosen version,
+   probe `catalog.getCanonicalDigest` and compare `sha256`.
+
+### Conflict error shape
+
+```
+error: divergent sha256 for skill:@skaile-ai/audit#1.4.0
+  pulled in via:
+    bundle:@skaile-ai/skaile-development#^2.0
+      skill:@skaile-ai/audit#~1.4
+  candidates:
+    https://github.com/skaile-ai/ai-assets @ 6a5266fd   sha256: 1da6294a...
+    https://github.com/mortegro/ai-assets-fork @ ab12cd34  sha256: 9e3f7c01...
+resolve by:
+  1. removing one source from skaile.yaml,
+  2. configuring a store and using its canonical digest, or
+  3. adding to overrides: (with a non-empty reason:)
+```
+
+## 7. Overrides
+
+```yaml
+overrides:
+  - ref: skill:@skaile-ai/audit#1.4.0      # the canonical, fully-pinned ref
+    source: https://github.com/skaile-ai/ai-assets   # which candidate wins
+    reason: "vendored patch for #42; revert when upstream merges"   # REQUIRED, non-empty
+```
+
+`reason:` is mandatory — empty/missing is a parse error. Use overrides only to
+break a genuine sha conflict; the right long-term fix is to stop publishing
+divergent bytes under the same coordinates.
+
+## 8. Version waterfall (recap)
+
+1. `assets[].version` in the source `skaile.yaml`
+2. source top-level `version:`
+3. SemVer git tag (`git describe --tags`, `v` stripped)
+4. synthetic `0.0.0-sha.<7char>`
+
+## 9. What changed from legacy (migration cheatsheet)
+
+| Legacy | Canonical (now) |
+|---|---|
+| `skill:audit@skaile-ai` | `skill:@skaile-ai/audit` |
+| `skill:audit@skaile-ai#1.4.0` | `skill:@skaile-ai/audit#1.4.0` |
+| bare `skill:audit` in a project dep | `skill:@<publisher>/audit` (publisher now required) |
+| `@skaile` publisher | `@skaile-ai` (rebrand) |
+| `repositories:` / `ai_resources:` top-level keys | `sources:` / `dependencies:` |
+
+**The legacy `kind:name@<publisher>` grammar no longer parses** — it is a hard
+error (`publisher required in asset ref`). The older `manifest-schema.md` line
+about "still parses for one release with a deprecation warning" is stale; the
+aliases were removed. Run the `migrate-skaile-manifest` skill to convert.
+
+## 10. Lock key
+
+The lock file (`skaile.lock.yaml`, schema v3) keys each entry by the
+fully-pinned canonical ref `kind:@<publisher>/name#version` and records the
+contributing source URL + commit and per-file `sha256`. Regenerate, never
+hand-edit: `rm skaile.lock.yaml && skaile install`.

package/dist/factory-assets/skills/manifest-compliance/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: manifest-compliance
+description: "Use when an AI-asset repo has manifests or skaile.yaml refs that fail canonical-name rules — the symptom is a runtime hard error like `publisher required in asset ref \"flow:@skaile-ai/CLI Concept\"` or `invalid asset name \"…\"` thrown by parseAssetRef at install/apply time. Scans a repo with `skaile validate`, then fixes each non-compliant asset identity (skill/agent `name`, flow `id`) to lowercase kebab-case and rewrites every reference (skaile.yaml dependencies/overrides, flow node skill refs, directory names). Trigger when the user says 'fix asset names', 'my manifest is invalid', 'publisher required error', 'invalid asset name', 'make my assets compliant', or 'migrate legacy manifest names'."
+metadata:
+  version: 1.0.0
+  source: AUTHORED
+  stage: beta
+  tags: [asset-store, manifest, compliance, validation, naming, migration, repo-author]
+  prerequisites:
+    inputs_optional:
+      - id: repo_path
+        label: "Path to the asset repo / library to check"
+        type: text
+        default: "."
+        hint: "Repo root — the tree containing SKILL.md / *.flow.yaml / skaile.yaml files"
+      - id: write
+        label: "Apply fixes vs report only"
+        type: boolean
+        default: false
+        hint: "If false, only report violations; if true, rename + rewrite refs"
+    reads:
+      - path: skills/authoring-skaile-manifests/references/dependency-standard.md
+        description: "Canonical dependency grammar + asset-ref shape"
+keywords: [manifest, compliance, asset-name, kebab-case, parseAssetRef, validate]
+---
+
+# Manifest Compliance
+
+Detect and fix asset manifests that violate the **canonical asset-name rule**,
+then rewrite every reference so the repo installs and applies without the
+`parseAssetRef` hard error.
+
+## The rule
+
+A canonical asset **name** (and a flow's **id**) is **lowercase kebab-case**:
+
+- allowed: `a-z`, `0-9`, single hyphens between segments
+- forbidden: uppercase, spaces, underscores, dots, leading/trailing or double hyphens
+
+A full reference is `kind:@<publisher>/name[#version]` — e.g.
+`flow:@skaile-ai/cli-concept`. A name like `"CLI Concept"` (space + uppercase)
+breaks the grammar; because the publisher is present, older builds reported the
+*misleading* `publisher required …` error — the real fault is the name.
+
+> A flow's `name:` frontmatter is a human-readable **display title** and may
+> contain spaces/uppercase. The asset identity is the flow's `id:` field —
+> that is what must be kebab-case. Fix `id`, leave `name` alone.
+
+## Step 0: Confirm context
+
+1. Resolve `repo_path` (default `.`).
+2. Confirm it's a repo/library tree (has `SKILL.md`, `*.flow.yaml`, or
+   `skaile.yaml` files somewhere under it).
+
+## Step 1: Detect (always run first)
+
+Run the repo-wide compliance check:
+
+```bash
+bun run cli validate <repo_path>
+```
+
+`skaile validate [path]` walks the tree and reports, per file:
+
+- `invalid asset name "…"` / `invalid asset id "…"` — a manifest identity that
+  isn't kebab-case (skill/agent `name`, flow `id`).
+- `[dependencies] / [overrides.ref] — …` — a `skaile.yaml` ref that fails
+  `parseAssetRef` (the exact path that hard-errors at runtime).
+- `[assets] — invalid asset name "…"` — a published `assets[]` entry identity.
+
+Exit code is `1` when any violation is found. Collect the full list before
+fixing — there are usually several, and references are interlinked.
+
+If validate is clean, report "compliant" and stop.
+
+## Step 2: Plan the renames
+
+For each violation, derive the compliant name and present the mapping to the
+user **before** writing:
+
+| Bad identity | Proposed kebab-case |
+|---|---|
+| `CLI Concept` | `cli-concept` |
+| `Test Echo Flow` | `test-echo-flow` |
+| `my_audit` | `my-audit` |
+
+Kebab-case derivation: lowercase, replace runs of non-`[a-z0-9]` with a single
+hyphen, trim leading/trailing hyphens. Flag collisions (two assets mapping to
+the same name) for the user to disambiguate — never auto-merge.
+
+## Step 3: Apply fixes (`write = true`)
+
+For each renamed asset, apply **all** of these so no dangling reference remains:
+
+1. **Manifest identity** — edit the `name:` (or, for flows, `id:`) field in the
+   asset's own manifest (`SKILL.md` frontmatter, `agent.yaml`, `*.flow.yaml`,
+   `MCP.md`, `CONNECTOR.md`, `*.preset.yaml`, etc.).
+2. **Directory name** — if the asset's folder is named after the old identity,
+   rename the directory to match (use `git mv` so history is preserved).
+3. **Inbound references** — grep the whole tree for the old identity and update
+   every occurrence:
+   - `skaile.yaml` → `dependencies:`, `overrides[].ref`, `assets[].name`
+   - flow nodes → `data.skill` / node refs that name the asset
+   - any `kind:@publisher/<old-name>` ref string anywhere
+
+   ```bash
+   grep -rn "<old-name>" <repo_path> --include="*.yaml" --include="*.md" --include="*.json"
+   ```
+
+   Review each hit — only rewrite genuine asset-ref occurrences, not prose.
+
+## Step 4: Verify
+
+Re-run the detector and confirm a clean tree:
+
+```bash
+bun run cli validate <repo_path>
+```
+
+Expect `All manifests valid` and exit `0`. If violations remain, return to
+Step 3 (a missed inbound reference, or a second-order collision).
+
+## Step 5: Suggest commit
+
+Summarize the renames applied (old → new) and the files touched, and suggest a
+commit message, e.g.:
+
+```
+fix(assets): make asset identities canonical kebab-case
+
+- flow "CLI Concept" → cli-concept (+ refs)
+```
+
+## CHECKLIST
+
+- [ ] Ran `skaile validate <repo_path>` and collected every violation
+- [ ] Proposed kebab-case mapping reviewed with the user (collisions flagged)
+- [ ] Fixed flow identity in `id:`, not `name:` (display title left intact)
+- [ ] Updated manifest identity, directory name, AND all inbound references
+- [ ] Re-ran `skaile validate` to a clean (exit 0) tree before committing