@skaile/workspaces 0.25.0 → 0.27.0

package/dist/factory-assets/connectors/webdav/CONNECTOR.md

@@ -0,0 +1,139 @@
+---
+name: webdav
+description: "WebDAV server connector via rclone FUSE."
+version: "0.3.0"
+entry: ./driver.ts
+fields:
+  - key: source
+    label: "WebDAV server URL"
+    required: true
+    sensitive: false
+  - key: auth
+    label: "Credentials (username:password or Bearer token)"
+    required: false
+    sensitive: true
+  - key: options.vendor
+    label: "WebDAV vendor (nextcloud | owncloud | sharepoint | fastmail | other). Default: other"
+    required: false
+    sensitive: false
+  - key: options.basePath
+    label: "Subfolder appended under the WebDAV URL"
+    required: false
+    sensitive: false
+  - key: options.cacheMaxSize
+    label: "rclone VFS cache size cap (e.g. '5G'). Default: 5G"
+    required: false
+    sensitive: false
+  - key: options.cacheMaxAge
+    label: "rclone VFS cache age cap (e.g. '168h'). Default: 168h"
+    required: false
+    sensitive: false
+  - key: options.vfsWriteBack
+    label: "rclone VFS write-back delay before upload (e.g. '30s', '1m'). Default: 30s"
+    required: false
+    sensitive: false
+keywords:
+  - webdav
+  - nextcloud
+  - owncloud
+  - fastmail
+  - rclone
+---
+
+## WebDAV Connector
+
+Exposes a WebDAV server directory via rclone's FUSE backend. The driver
+delegates the entire data plane (enumeration, download, upload, change
+detection, cache management) to an `rclone mount` subprocess managed by
+`RcloneProcessManager`.
+
+### Configuration
+
+```yaml
+connectors:
+  - id: shared-docs
+    driver: webdav
+    access: read-write
+    auth: env:WEBDAV_CREDENTIALS
+    mount:
+      source: https://cloud.example.com/remote.php/dav/files/user
+    options:
+      vendor: nextcloud
+      basePath: Documents/project
+      cacheMaxSize: 5G
+      cacheMaxAge: 168h
+      vfsWriteBack: 30s
+```
+
+`vfsWriteBack` controls rclone's `--vfs-write-back` — how long a dirty file
+sits before upload. Default raised from 5s to 30s so a rapidly-rewritten file
+settles before transfer instead of aborting with `sizes differ`.
+
+`mount.source` is the WebDAV endpoint URL. `basePath` is an optional subfolder
+appended to that URL when constructing the rclone remote.
+
+### NextCloud / ownCloud
+
+NextCloud and ownCloud expose a standard WebDAV endpoint at
+`https://<host>/remote.php/dav/files/<username>`. Set `vendor: nextcloud`
+(or `owncloud`) so rclone uses the right quirks.
+
+```yaml
+connectors:
+  - id: nextcloud-docs
+    driver: webdav
+    access: read-write
+    auth: env:NEXTCLOUD_CREDENTIALS
+    mount:
+      source: https://nextcloud.example.com/remote.php/dav/files/alice
+    options:
+      vendor: nextcloud
+      basePath: Documents/project
+```
+
+### Authentication
+
+The `auth` field resolves to one of:
+- `username:password` -- Basic/Digest authentication. The first colon
+  separates the two parts; passwords containing colons are preserved.
+- A bare token string -- Bearer token authentication (OAuth WebDAV).
+- Empty / undefined -- anonymous WebDAV (no auth header).
+
+Plaintext passwords are passed through `rclone obscure` before being written
+into the rclone config — rclone's `pass` field is not plaintext.
+
+### Implementation: rclone FUSE
+
+- **mount**: Renders an `[skaile-<id>]` rclone config (webdav backend, URL +
+  vendor + obscured credentials), spawns `rclone mount` with VFS caching,
+  returns once the FUSE mountpoint is confirmed in `/proc/self/mounts`.
+- **VFS cache mode**: `read-only` mounts use `minimal`; `read-write` uses
+  `full` so writes are buffered locally before upload.
+- **Cache directory**: `/var/cache/skaile/<mountId>` (the parent
+  `/var/cache/skaile` is bind-mounted from the host per session).
+- **sync**: Calls `RcloneProcessManager.flush` (POSTs `/vfs/refresh` then waits
+  for the in-use counter to reach zero).
+- **unmount**: `RcloneProcessManager.stop` flushes, sends SIGTERM, falls back
+  to SIGKILL + `fusermount3 -u` after a 30s grace.
+- **onHibernate / onSessionClose**: Always flush. Cheap and the right default;
+  no opt-out toggles.
+- **Logs**: rclone subprocess JSON log lines are routed through a child
+  logger with subkind `webdav+rclone`, alongside the driver's own
+  `webdav` entries — both visible via `skaile session logs --kind mount`.
+
+### Fleet-managed mode (Phase 7B)
+
+When the `SKAILE_FLEET_MANAGED_MOUNTS` env var lists this mount's id, the
+host-side `RcloneFleetService` (in the platform backend) has already
+spawned a shared `rclone mount` process and bind-mounted its FUSE
+mountpoint into the container at the driver's `targetDir`. The driver
+short-circuits its own rclone spawn:
+
+- `mount()` verifies the bind mount is live (`stat` + `readdir` poll up
+  to 3s), then returns a no-op handle with `state.fleetManaged = true`.
+- `unmount()`, `sync()`, `onHibernate()`, `onSessionClose()` all return
+  early — the fleet owns the rclone process and is responsible for
+  flushing and teardown.
+
+The env var is comma-separated; an empty / unset value preserves the
+per-session behaviour described above.

package/dist/{base-assets → factory-assets}/connectors/webdav/driver.d.ts

@@ -14,7 +14,7 @@ import { AbstractConnector } from "@skaile/workspaces/connectors";
  * Fastmail, generic) — delegates the data plane to an `rclone mount` subprocess via
  * `RcloneProcessManager`. Supports fleet-managed mode where the host has pre-mounted
  * the share via `SKAILE_FLEET_MANAGED_MOUNTS`.
- * @docLink packages/base-assets/concepts#webdav-connector
+ * @docLink packages/factory-assets/concepts#webdav-connector
  */
 export declare class WebDAVConnector extends AbstractConnector {
     readonly name = "webdav";
@@ -29,7 +29,7 @@ export declare class WebDAVConnector extends AbstractConnector {
 /**
  * Creates a new WebDAVConnector instance.
  * @returns Configured WebDAVConnector ready to be registered in the connector registry.
- * @docLink packages/base-assets/api-reference#webdav-connector-factory
+ * @docLink packages/factory-assets/api-reference#webdav-connector-factory
  */
 export declare function createConnector(): WebDAVConnector;
 //# sourceMappingURL=driver.d.ts.map

package/dist/factory-assets/connectors/webdav/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../../factory-assets/connectors/webdav/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,cAAc,EAIf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,iBAAiB,EAQlB,MAAM,+BAA+B,CAAC;AAwBvC;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,iBAAiB;IACpD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,MAAM,CAA8B;IAE5C,QAAQ,CAAC,UAAU,EAAE,cAAc,CAKjC;IAEI,OAAO,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAsGzF,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;YAM1C,KAAK;IAwBJ,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAOjE,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAMpF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAEjD"}

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

@@ -0,0 +1,22 @@
+export { WebDAVConnector, createConnector5 as createConnector } from '../../chunk-XHBPQ7QP.js';
+import '../../chunk-OVRSNIKJ.js';
+import '../../chunk-DGM74UP4.js';
+import '../../chunk-QMONOHXT.js';
+import '../../chunk-6E6PKKAD.js';
+import '../../chunk-W7W66MDZ.js';
+import '../../chunk-DEYYRFQU.js';
+import '../../chunk-IFGTRL2I.js';
+import '../../chunk-M4KLIEIJ.js';
+import '../../chunk-FWHOU3CX.js';
+import '../../chunk-3QQSSRYN.js';
+import '../../chunk-IERB3UXJ.js';
+import '../../chunk-2FS4FPZ7.js';
+import '../../chunk-IEJ5IOC3.js';
+import '../../chunk-JKNWJ64A.js';
+import '../../chunk-O4JH3KUE.js';
+import '../../chunk-K5GBV4SA.js';
+import '../../chunk-ZAP2BDHG.js';
+import '../../chunk-24UIWON4.js';
+import '../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=webdav.js.map
+//# sourceMappingURL=webdav.js.map

package/dist/factory-assets/connectors/xstate/CONNECTOR.md

@@ -0,0 +1,57 @@
+---
+name: xstate
+description: "Full state machine resource via XState v5"
+version: "0.1.0"
+entry: ./adapter.ts
+npm_deps:
+  required:
+    - xstate
+  optional:
+    - yaml
+fields: []
+health_check: null
+keywords:
+  - state-machine
+  - xstate
+  - fsm
+  - workflow
+---
+
+A state machine connector using XState v5. Provides guarded transitions,
+entry/exit actions, context, and serializable snapshots.
+
+Machine definitions can be provided inline via `options.machine` or loaded
+from a YAML/JSON file via `options.definitionPath`.
+
+## Operations
+
+| Operation | Access | Description |
+|-----------|--------|-------------|
+| `get_state` | read | Get current state, context, and available transitions |
+| `get_definition` | read | Get the machine definition |
+| `history` | read | Get the transition history log |
+| `can` | read | Check if a transition is currently allowed |
+| `send` | write | Send an event to trigger a transition |
+
+## Configuration
+
+```yaml
+connectors:
+  - id: approval
+    adapter: xstate
+    access: read-write
+    options:
+      machine:
+        id: approval
+        initial: draft
+        states:
+          draft:
+            on:
+              SUBMIT: review
+          review:
+            on:
+              APPROVE: approved
+              REJECT: draft
+          approved:
+            type: final
+```

package/dist/{base-assets → factory-assets}/connectors/xstate/adapter.d.ts

@@ -11,7 +11,7 @@ import type { ConnectContext, ConnectorDeclaration, ConnectorHandle, ToolFace }
  * Connector for XState v5 state machines — drives guarded transitions, tracks history, and exposes
  * the current state and context to agents. Machine definitions can be provided inline or loaded
  * from a JSON/YAML file. Requires the `xstate` optional peer dependency.
- * @docLink packages/base-assets/concepts#xstate-connector
+ * @docLink packages/factory-assets/concepts#xstate-connector
  */
 export declare class XStateConnector extends AbstractConnector {
     readonly name = "xstate";
@@ -47,7 +47,7 @@ export declare class XStateConnector extends AbstractConnector {
 /**
  * Creates a new XStateConnector instance.
  * @returns Configured XStateConnector ready to be registered in the connector registry.
- * @docLink packages/base-assets/api-reference#xstate-connector-factory
+ * @docLink packages/factory-assets/api-reference#xstate-connector-factory
  */
 export declare function createConnector(): XStateConnector;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/factory-assets/connectors/xstate/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../factory-assets/connectors/xstate/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,+BAA+B,CAAC;AAmBvC;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,iBAAiB;IACpD,QAAQ,CAAC,IAAI,YAAY;IAEzB,KAAK,EAAE,QAAQ,CAAC;;IAaV,OAAO,CAAC,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IA8E1F,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD,OAAO,CAAC,CAAC;IAIT;;OAEG;IACH,eAAe,CACb,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC,GAChD,IAAI;IAIP;;OAEG;IACH,cAAc,CACZ,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAClD,IAAI;IAIP;;OAEG;IACH,aAAa,CACX,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,CAAC,QAAQ,EAAE;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAE,KAAK,IAAI,GACnD,IAAI;YAMO,KAAK;YAcL,KAAK;YAkBL,OAAO;IASrB,OAAO,CAAC,mBAAmB;YA0Db,UAAU;IA+FxB,OAAO,CAAC,kBAAkB;IAS1B,0EAA0E;IAC1E,OAAO,CAAC,YAAY;CAwBrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAEjD"}

package/dist/factory-assets/connectors/xstate-store/CONNECTOR.md

@@ -0,0 +1,48 @@
+---
+name: xstate-store
+description: "Lightweight typed event store via @xstate/store"
+version: "0.1.0"
+entry: ./adapter.ts
+npm_deps:
+  required:
+    - "@xstate/store"
+  optional: []
+fields: []
+health_check: null
+keywords:
+  - store
+  - state
+  - xstate
+  - kv
+  - reactive
+---
+
+A lightweight event-driven store using @xstate/store. Provides a shared
+key-value store between UI and agents with event history.
+
+For typed/validated state machines with guards and actions, use the
+`xstate` adapter instead.
+
+## Operations
+
+| Operation | Access | Description |
+|-----------|--------|-------------|
+| `get` | read | Get full store snapshot |
+| `get_key` | read | Get a single value by key |
+| `history` | read | Get event history log |
+| `set` | write | Set a key to a value |
+| `merge` | write | Merge an object into the store context |
+| `reset` | write | Reset the store to initial context |
+
+## Configuration
+
+```yaml
+connectors:
+  - id: app-state
+    adapter: xstate-store
+    access: read-write
+    options:
+      initial:
+        theme: dark
+        locale: en
+```

package/dist/{base-assets → factory-assets}/connectors/xstate-store/adapter.d.ts

@@ -9,7 +9,7 @@ import { AbstractConnector } from "@skaile/workspaces/connectors";
 /**
  * Connector for `@xstate/store` — a lightweight event-driven key-value store shared between agents and UI clients.
  * Provides get, set, merge, and reset operations with an event history log. Requires the `@xstate/store` optional peer dependency.
- * @docLink packages/base-assets/concepts#xstate-store-connector
+ * @docLink packages/factory-assets/concepts#xstate-store-connector
  */
 export declare class XStateStoreConnector extends AbstractConnector {
     readonly name = "xstate-store";
@@ -35,7 +35,7 @@ export declare class XStateStoreConnector extends AbstractConnector {
 /**
  * Creates a new XStateStoreConnector instance.
  * @returns Configured XStateStoreConnector ready to be registered in the connector registry.
- * @docLink packages/base-assets/api-reference#xstate-store-connector-factory
+ * @docLink packages/factory-assets/api-reference#xstate-store-connector-factory
  */
 export declare function createConnector(): XStateStoreConnector;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/factory-assets/connectors/xstate-store/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../factory-assets/connectors/xstate-store/adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EAEd,oBAAoB,EAEpB,eAAe,EAKf,QAAQ,EACT,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAQlE;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,KAAK,EAAE,QAAQ,CAAC;;IAeV,OAAO,CAAC,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAuC1F,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI;YAM/E,KAAK;YAWL,MAAM;YAgBN,OAAO;YAQP,KAAK;YAkBL,OAAO;IAiBrB,OAAO,CAAC,mBAAmB;YAiFb,UAAU;IAgFxB,OAAO,CAAC,cAAc;CAKvB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,oBAAoB,CAEtD"}

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

@@ -0,0 +1,22 @@
+export { XStateStoreConnector, createConnector13 as createConnector } from '../../chunk-XHBPQ7QP.js';
+import '../../chunk-OVRSNIKJ.js';
+import '../../chunk-DGM74UP4.js';
+import '../../chunk-QMONOHXT.js';
+import '../../chunk-6E6PKKAD.js';
+import '../../chunk-W7W66MDZ.js';
+import '../../chunk-DEYYRFQU.js';
+import '../../chunk-IFGTRL2I.js';
+import '../../chunk-M4KLIEIJ.js';
+import '../../chunk-FWHOU3CX.js';
+import '../../chunk-3QQSSRYN.js';
+import '../../chunk-IERB3UXJ.js';
+import '../../chunk-2FS4FPZ7.js';
+import '../../chunk-IEJ5IOC3.js';
+import '../../chunk-JKNWJ64A.js';
+import '../../chunk-O4JH3KUE.js';
+import '../../chunk-K5GBV4SA.js';
+import '../../chunk-ZAP2BDHG.js';
+import '../../chunk-24UIWON4.js';
+import '../../chunk-NSBPE2FW.js';
+//# sourceMappingURL=xstate-store.js.map
+//# sourceMappingURL=xstate-store.js.map

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

@@ -0,0 +1,22 @@
+export { XStateConnector, createConnector12 as createConnector } from '../../chunk-XHBPQ7QP.js';
+import '../../chunk-OVRSNIKJ.js';
+import '../../chunk-DGM74UP4.js';
+import '../../chunk-QMONOHXT.js';
+import '../../chunk-6E6PKKAD.js';
+import '../../chunk-W7W66MDZ.js';
+import '../../chunk-DEYYRFQU.js';
+import '../../chunk-IFGTRL2I.js';
+import '../../chunk-M4KLIEIJ.js';
+import '../../chunk-FWHOU3CX.js';
+import '../../chunk-3QQSSRYN.js';
+import '../../chunk-IERB3UXJ.js';
+import '../../chunk-2FS4FPZ7.js';
+import '../../chunk-IEJ5IOC3.js';
+import '../../chunk-JKNWJ64A.js';
+import '../../chunk-O4JH3KUE.js';
+import '../../chunk-K5GBV4SA.js';
+import '../../chunk-ZAP2BDHG.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