@skaile/workspaces 0.25.0 → 0.26.0

package/dist/factory-assets/connectors/xstate.js

@@ -0,0 +1,22 @@
+export { XStateConnector, createConnector12 as createConnector } from '../../chunk-YDTW4GT6.js';
+import '../../chunk-ZYDE52WE.js';
+import '../../chunk-QMONOHXT.js';
+import '../../chunk-OVRSNIKJ.js';
+import '../../chunk-6E6PKKAD.js';
+import '../../chunk-W7W66MDZ.js';
+import '../../chunk-DEYYRFQU.js';
+import '../../chunk-IFGTRL2I.js';
+import '../../chunk-KL2MQ6WI.js';
+import '../../chunk-K5GBV4SA.js';
+import '../../chunk-ZAP2BDHG.js';
+import '../../chunk-C32BRO2W.js';
+import '../../chunk-Z5DI7PDG.js';
+import '../../chunk-IERB3UXJ.js';
+import '../../chunk-2FS4FPZ7.js';
+import '../../chunk-IEJ5IOC3.js';
+import '../../chunk-JKNWJ64A.js';
+import '../../chunk-O4JH3KUE.js';
+import '../../chunk-24UIWON4.js';
+import '../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=xstate.js.map
+//# sourceMappingURL=xstate.js.map

package/dist/{base-assets → factory-assets}/index.d.ts

@@ -2,7 +2,7 @@
  * Eagerly loads all built-in connector adapters and mount drivers.
  * Intended for use in environments where lazy loading via subpath imports is not desired.
  * Individual adapters and drivers are normally loaded on demand by the connector and mount registries.
- * @docLink packages/base-assets/api-reference#base-assets
+ * @docLink packages/factory-assets/api-reference#factory-assets
  */
 export declare function registerAll(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/factory-assets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../factory-assets/index.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD"}

package/dist/{base-assets → factory-assets}/index.js

@@ -1,6 +1,6 @@
 import '../chunk-NSBPE2FW.js';
 
-// base-assets/index.ts
+// factory-assets/index.ts
 async function registerAll() {
 }
 

package/dist/factory-assets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../factory-assets/index.ts"],"names":[],"mappings":";;;AAUA,eAAsB,WAAA,GAA6B;AAEnD","file":"index.js","sourcesContent":["// factory-assets — first-party framework content (built-in connectors + skills + bundles)\n// Subpath imports: @skaile/workspaces/factory-assets/connectors/<name>\n// This root export provides registerAll() for eager loading of all built-in adapters/drivers.\n\n/**\n * Eagerly loads all built-in connector adapters and mount drivers.\n * Intended for use in environments where lazy loading via subpath imports is not desired.\n * Individual adapters and drivers are normally loaded on demand by the connector and mount registries.\n * @docLink packages/factory-assets/api-reference#factory-assets\n */\nexport async function registerAll(): Promise<void> {\n  // Populated in Phase 3 after implementations are moved here\n}\n"]}

package/dist/factory-assets/skaile.manifest.yaml

@@ -0,0 +1,25 @@
+# Publication manifest for the workspaces-authoring asset set.
+# This repo IS a source (publication half only). See skills/authoring-skaile-manifests.
+publisher: skaile-ai
+version: 0.1.0
+
+assets:
+  - kind: skill
+    name: authoring-skaile-assets
+    root: skills/authoring-skaile-assets
+  - kind: skill
+    name: authoring-skaile-manifests
+    root: skills/authoring-skaile-manifests
+  - kind: skill
+    name: skaile-author-asset
+    root: skills/skaile-author-asset
+  - kind: skill
+    name: skaile-manage-workspace
+    root: skills/skaile-manage-workspace
+  - kind: skill
+    name: manifest-compliance
+    root: skills/manifest-compliance
+  - kind: bundle
+    name: workspaces-authoring
+    files:
+      - bundles/workspaces-authoring/workspaces-authoring.bundle.yaml

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

@@ -0,0 +1,176 @@
+---
+name: authoring-skaile-assets
+description: "Use when authoring or restructuring an AI-asset repository (skills, agents, prompts, contracts, MCP servers, connectors, flows, bundles) so it resolves cleanly through @skaile/workspaces and any store. Covers file layout, the 11 asset kinds, frontmatter conventions, the requires-vs-dependencies split, and how to test a source locally before publishing."
+metadata:
+  version: '0.1.0'
+  stage: alpha
+  tags:
+    - skaile
+    - workspaces
+    - authoring
+    - skill
+    - asset
+    - source
+    - publish
+  requires:
+    - skill:authoring-skaile-manifests
+---
+
+# Authoring assets for `@skaile/workspaces`
+
+You are helping an author build or fix an **AI-asset repository** (a "source") so
+that `@skaile/workspaces` — and any store mirroring it — can discover, resolve,
+and deploy its assets. This skill owns the *content* side (files on disk). Its
+companion **[authoring-skaile-manifests]** owns the `skaile.yaml` manifest and
+the dependency grammar; read it before publishing.
+
+## Mental model
+
+A **source** is a git repo of asset bytes. Identity is the global tuple
+`(publisher, kind, name, version)` and is **asset-intrinsic** — declared in the
+source's own `skaile.yaml`, never chosen by the consuming project. A consumer
+reaches the bytes by cloning the source repo (`sources[]`) or by querying a
+catalog (`stores[]`); both paths are content-hash verified and interchangeable.
+
+> Vocabulary: **source** holds bytes (a repo). **library** is a place on the
+> author's machine where they hold/author bytes. **store** is a remote catalog of
+> *manifests* that point at sources — it holds no bytes.
+
+## The 11 asset kinds
+
+| Kind | Manifest file | Identity name from |
+|---|---|---|
+| `skill` | `SKILL.md` | frontmatter `name:` → else parent dir |
+| `agent` | `AGENT.md` **or** `agent.yaml` | `name:` → else parent dir |
+| `prompt` | `*.prompt.md` | `name:` → else filename stem |
+| `contract` | `CONTRACT.md` | `name:` → else parent dir |
+| `mcp-server` | `MCP.md` | `name:` → else parent dir |
+| `connector` | `CONNECTOR.md` | `name:` → else parent dir |
+| `knowledge` | `knowledge.yaml` | `name:` → else parent dir |
+| `persona` | `SKILL.md` with `type: persona` | `name:` → else parent dir |
+| `ruleset` | `SKILL.md` with `type: ruleset` | `name:` → else parent dir |
+| `flow` | `*.flow.yaml` / `*.flow.json` | `name:`/`id:` → else filename stem |
+| `bundle` | `*.bundle.yaml` | `name:` → else filename stem |
+
+`mcp:` is a shorthand alias for `mcp-server:` in refs.
+`persona`/`ruleset` are composition fragments selected via a `SKILL.md`
+`type:` key (they replace the old `SOUL.md`/`RULES.md`).
+
+## File layout — two options
+
+**A. Explicit (recommended for curated repos).** Put `skaile.yaml` at the repo
+root with an `assets:` list and lay files out however you like; `root:`/`files:`
+point at each asset. See [authoring-skaile-manifests].
+
+**B. Convention (zero-config).** Omit `skaile.yaml`; the walker falls back to the
+agentskills.io layout:
+
+```
+<repo-root>/<kind-plural>/<name>/<KIND>.md
+  skills/audit/SKILL.md
+  agents/reviewer/AGENT.md
+  mcp-servers/excel/MCP.md
+```
+
+> ⚠️ If `skaile.yaml` has a **non-empty `assets:` list, it is exhaustive** — only
+> listed assets are resolvable. Files on disk that you forgot to list still show
+> up in `skaile manage` (the browse scan walks the filesystem) but **fail at
+> install** with `Asset not found`. Keep the list complete, or omit it and rely
+> on convention. This is the #1 authoring footgun.
+
+## Frontmatter conventions (`SKILL.md` et al.)
+
+Follow the agentskills.io convention: identity at the top level, skaile
+extensions nested under `metadata:` (both locations are read for `version` and
+`requires`, so either works).
+
+```markdown
+---
+name: audit                       # MUST equal the assets[].name in skaile.yaml
+description: "Use when ..."        # one line; this is what the model matches on
+metadata:
+  version: '1.4.0'                 # source skaile.yaml is authoritative; this is a hint only
+  stage: stable
+  tags: [review, quality, ci]
+  requires:                        # peer assets this one needs — kind:name form
+    - contract:implementation-contract
+    - skill:use-exa
+---
+
+# Audit
+...skill body the agent reads at runtime...
+```
+
+Rules that bite:
+- **`name:` MUST equal the `assets[].name`** in `skaile.yaml`. Mismatch is an
+  index-time hard error.
+- `metadata.version` is **ignored for resolution** — the source `skaile.yaml`
+  version (or git-tag waterfall) is authoritative. Keep it as documentation only.
+- `description:` is the model-facing trigger. Write it as "Use when …"; it
+  decides whether the skill gets surfaced.
+
+## `requires:` vs `dependencies:` — don't confuse them
+
+| Field | Where | Form | Resolves to |
+|---|---|---|---|
+| `requires:` | content frontmatter (`SKILL.md`, `agent.yaml`) | **`kind:name`** (bare) | a peer asset in the *same source* — publisher inherited |
+| `dependencies:` | a **bundle** manifest, or a *project's* `skaile.yaml` | **full canonical ref** `kind:@publisher/name[#version]` | any asset, cross-source |
+
+So a skill that needs a co-located contract writes `requires: [contract:implementation-contract]`.
+A bundle that fans out across publishers writes
+`dependencies: [skill:@skaile-ai/audit#^1.4, skill:@vercel-labs/agent-skills]`.
+The full grammar lives in [authoring-skaile-manifests].
+
+## Bundles — group assets for one-shot install
+
+A `*.bundle.yaml` lists canonical refs; installing the bundle pulls every member
+(and nested bundles, any depth — cycles are de-duped).
+
+```yaml
+name: mvp
+version: 1.0.0
+description: "MVP pipeline: concept → spec → mockup → build."
+dependencies:
+  - skill:@skaile-ai/concept-brief
+  - skill:@skaile-ai/product-spec-features#^1.0
+  - agent:@skaile-ai/impl-build-implement
+```
+
+## Authoring checklist
+
+1. Pick the kind + name; create the manifest file (`SKILL.md`, `agent.yaml`, …).
+2. Write a sharp `description:` ("Use when …").
+3. Declare same-source peers in `requires:` (`kind:name`).
+4. If publishing as a curated source: add the asset to `skaile.yaml` `assets:`
+   and confirm `name:` matches. Run [authoring-skaile-manifests] to author/verify.
+5. Test locally before pushing (below).
+6. Commit; tag a SemVer release (`vX.Y.Z`) so the version waterfall resolves.
+
+## Test a source locally — no publish needed
+
+```bash
+# In a throwaway consumer project:
+skaile init
+skaile source add <path-or-git-url>        # register your repo as a source
+skaile source sync                          # clone/refresh + rebuild manifest cache
+skaile manage                               # browse the tree — every asset should appear
+skaile add skill:@<publisher>/<name>        # resolve+deploy one asset; watch for "Asset not found"
+skaile catalog test                         # debug the read protocol (resolve/list)
+skaile install                              # resolve the full dependency closure
+```
+
+If `skaile manage` shows an asset but `skaile add` errors `Asset not found`, the
+asset is on disk but missing from the `assets:` list — see the footgun warning
+above.
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Asset not found` on an asset visible in `manage` | omitted from `assets:` | add it, or drop `assets:` and use convention |
+| `name mismatch` at index time | `SKILL.md` `name:` ≠ `assets[].name` | make them equal |
+| `publisher must be declared` | non-GitHub source URL, no `publisher:` | set `publisher:` in `skaile.yaml` |
+| `publisher required in asset ref` | a dep uses legacy `kind:name@pub` | migrate to `kind:@pub/name` (see [authoring-skaile-manifests]) |
+| dep silently absent at runtime | `requires:` used a full canonical ref | `requires:` is `kind:name` only; full refs go in bundle/project `dependencies:` |
+
+[authoring-skaile-manifests]: ../authoring-skaile-manifests/SKILL.md

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