@skaile/workspaces 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,400 @@
 # Changelog
 
+## 1.5.0
+
+### Minor Changes
+
+- [#340](https://github.com/skaile-ai/workspaces/pull/340) [`cde9457`](https://github.com/skaile-ai/workspaces/commit/cde9457c22d7e58111156effec1d4f5a8b9c50ec) Thanks [@henkbla](https://github.com/henkbla)! - `app-sdk`: connection-param handshake, reconnect, and registration replay.
+
+  The embedded app needs three things to open its back-connection — the gateway
+  URL, its `appId`, and a session identity token. The token is a credential, and
+  the preview surface that serves the app is unauthenticated, so it must not ride
+  in the iframe `src`. `resolveAppConnectionParams()` obtains it over
+  `postMessage` instead: the app posts a `skaile_app_ready` ping to its embedder
+  and awaits a `skaile_app_params` reply, with both sides pinning the peer on
+  `event.origin` **and** `event.source`. The app learns the expected host origin
+  from a non-secret `skaileParentOrigin` query param — safe to leak precisely
+  because it is not a credential. `"*"` and `"null"` host origins are refused: an
+  unpinnable peer defeats the point of keeping the token out of the URL.
+
+  `createWebSocketAppTransport` now accepts a `SessionTokenProvider` for
+  `sessionToken` as well as a bare string. The gateway's token is **single-use**
+  (consumed at `app_hello`), so a reconnecting transport cannot replay the one it
+  opened with; a provider mints a fresh token per attempt. A bare string still
+  opens the socket synchronously.
+
+  `createSkaileApp` gains a `reconnect` policy (default
+  `{maxAttempts:5, baseMs:1000, maxMs:30000}`, or `false` to disable). It rebinds
+  after a dropped socket and **replays its capability registry**, since the
+  gateway deregisters an app's capabilities when its connection closes. It also
+  retries a _retryable_ `app_hello_nack` — the app boots independently of the
+  session's agent container and can win that race. A permanent refusal (bad token,
+  `appId` not permitted) is never retried, because retrying only burns tokens.
+  `AppHelloNackMessage` gains an optional `retryable` field to carry that
+  distinction, and the SDK surfaces it as `AppHandshakeRefusedError.retryable`.
+  New `onSessionChange(handler)` fires on every bind — including the initial
+  `connect()` — and with `null` whenever the connection drops.
+
+  Behaviour change for `1.4.0` consumers: reconnect is **on by default**, so a
+  dropped socket now re-dials instead of leaving the app inert. Pass
+  `reconnect: false` for the old single-shot behaviour. Purely additive otherwise
+  — new exports, a widened `sessionToken` type, and one new optional wire field.
+
+- [#344](https://github.com/skaile-ai/workspaces/pull/344) [`fdd6c6a`](https://github.com/skaile-ai/workspaces/commit/fdd6c6a2bf89b677274665edd31ba9c6f71e5408) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Wire `skaile library publish` / `register` / `yank` — first-party store publish
+
+  Publish a git-backed library you own (in-repo `skaile.manifest.yaml`) to the
+  store: `library publish <lib>` commits + pushes the library repo, registers +
+  syncs it as a store source (no sidecar — the in-repo manifest drives discovery),
+  and publishes its assets under the manifest's own `publisher` (no namespace
+  remap). `--asset <ref>` narrows to one asset; `--create-repo` provisions + links
+  a public `github.com/<you>/<lib>` via `gh` when the library has no remote;
+  `--dry-run` prints an offline plan. `register` skips the commit/push (already on
+  GitHub); `yank` unpublishes. Requires a public git remote + `store login`.
+
+  Extracts the shared store-interaction core (`publish-core.ts` `publishToStore`)
+  reused by both `library publish` and `source manifest publish`, so the two
+  front-ends can't drift on the register → sync → candidates → per-asset publish
+  sequence.
+
+- [#335](https://github.com/skaile-ai/workspaces/pull/335) [`84565e0`](https://github.com/skaile-ai/workspaces/commit/84565e09c4da6daab4f26d9402cefd42884588ce) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar authoring + consume bug fixes for third-party sources.
+
+  **Sidecar authoring (`skaile source manifest init` / `edit` + overlay read + add).** You can
+  now curate assets from a foreign GitHub repo you don't control by authoring a
+  `skaile.manifest.yaml` stored _outside_ that repo, then consume + `add` them under a clean
+  curated publisher.
+
+  - `skaile source manifest init <src> [--publisher <name>] [--dev] [--force]` — clone (if
+    needed), run discovery, and write a curated manifest to the local store catalog at
+    `~/.skaile/store/manifests/<slug>.yaml`. Publisher defaults to the source's GitHub org.
+    Every asset inherits the top-level publisher (no per-asset path-segment stamp).
+    Idempotent (won't overwrite without `--force`).
+  - `skaile source manifest edit <src>` — open the curated manifest in `$EDITOR` and
+    re-validate on save (warnings surfaced, never a hard fail).
+  - `skaile source add` / `source sync` apply the curated manifest as a **read overlay**:
+    the curated publisher + asset inventory win over raw glob discovery. `LocalCatalogSource`
+    gained a `sidecarManifestFile` option; discovery gained `loadMergedSourceConfigFromFile`
+    - a `sidecarManifestFile` discovery option; the library gained `writeCuratedManifest`.
+  - `skaile add` now resolves the curated publisher too: the provenance walker
+    (`buildProvenanceIndex`) reads the same curated store overlay (via a new
+    `SourceClone.overlayManifestPath`), so the ref `search --local` displays
+    (`skill:@lark/…`) is the ref `add` accepts and deploys.
+  - Store manifests are keyed by a collision-free `storeManifestSlug(url)`
+    (`<host>__<owner>__<repo>`), so two repos sharing a trailing name (`orgA/cli`,
+    `orgB/cli`) no longer collide on `cli.yaml`.
+
+  **Bug fix — publisher normalization (glob AND manifest paths).** Discovery stored
+  publishers _with_ a leading `@`, which the local ref formatter doubled into `@@scripts`
+  (glob) / made `@lark` assets un-addable (manifest/curated overlay). `DiscoveredAsset.publisher`
+  is now **bare** on every discovery path (glob + manifest, local-FS + virtual-tree), unifying
+  them; the single `@` scope sigil is re-added by the ref formatter, and refs carry exactly
+  one `@` across both modes. The internal `SourceConfig` layer (`publisher_default` /
+  `atPublisher`) is unchanged — the `@`-prefix is correct there.
+
+  **Bug fix — `search --local` reads the index (and unions the factory source).** It now
+  reads the index (`asset_definitions` via `listAssetDefs`) instead of re-scanning the repo
+  tree, so its result set and count match exactly what `source add`/`sync` wrote — no scanner
+  `kind:name` dedup collapsing same-named or multi-kind assets — and unions the bundled
+  first-party factory source (never indexed) so built-in skills still appear in a fresh
+  project.
+
+- [#339](https://github.com/skaile-ai/workspaces/pull/339) [`56776b2`](https://github.com/skaile-ai/workspaces/commit/56776b2c709d08d2aff0f46a19cd876db52db5b0) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Wire `skaile source manifest publish` and `yank` — the curator publish flow
+
+  `source manifest publish <src>` takes a locally-curated sidecar manifest (over a
+  foreign **public** GitHub repo), pushes it to a public "sidecar" repo you own,
+  then registers + syncs the source with the store and publishes each curated asset
+  under your namespace (default: your store username; `--as <ns>` to override, e.g.
+  a GitHub org you belong to). `--dry-run` prints an offline plan (no push, no store
+  calls). `yank` unpublishes the source's published assets; `propose` stays a stub.
+
+  Requires the store's self-service `sources.add` sidecar support (skaile-store#79)
+  and a deployed store backend. Mono-repo sidecars (`sidecar_path`) are a documented
+  follow-up.
+
+- [#338](https://github.com/skaile-ai/workspaces/pull/338) [`9e959ee`](https://github.com/skaile-ai/workspaces/commit/9e959eec7d3c935aaa3c6c0c001f366b2bdbd80c) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar authoring phase 3 — wire `skaile source manifest rebuild` / `verify`,
+  extend the init test-fixture filter, and fix key-aware legacy clone migration.
+
+  - **`source manifest rebuild <src>` (new verb).** Refreshes a curated manifest
+    after the upstream repo changed. **Merge is the default — curation is sacred:**
+    it updates the clone (`git pull --ff-only`, best-effort), re-runs discovery,
+    and matches existing↔discovered entries by repo-relative `root` path. Existing
+    entries whose root is still present are KEPT verbatim (all hand-edits
+    preserved: publisher, per-asset name/version/description); entries whose root
+    is gone upstream are DROPPED and reported (`removed (gone upstream): …`).
+    Freshly-discovered assets not already curated are NOT auto-added — they are
+    reported (`N new upstream asset(s) available (not added): … — add with
+\`skaile source manifest edit\``), so a curated foreign-repo sidecar never
+silently absorbs new upstream skills, and an asset the curator deliberately
+dropped stays dropped. Writes only when something changed (else `already up to
+    date`). `--overwrite`re-scans the full inventory with`init --force`
+    semantics, warning that curation is replaced.
+  - **`source manifest verify <src>` (new verb), read-only.** Checks each manifest
+    asset against the clone: `root`/`files` paths still exist upstream (missing →
+    error); a declared `sha256` on a **`files:` entry** recomputes to the same
+    deterministic composite hash (mismatch → error) — hashed exactly as discovery
+    does (repo-root anchored, files verbatim as repo-relative strings), so a
+    correctly-pinned hash verifies clean; a declared `sha256` on a `root:` entry is
+    **skipped with a warning** (discovery hashes only the per-kind filtered set, so
+    a whole-dir recompute would false-mismatch, and the writer never emits sha256
+    for `root:` entries); schema decodes cleanly (`decodeSkaileManifest`
+    diagnostics → warnings/errors); dependency refs parse (`parseAssetRef`;
+    malformed → warning). Prints a summary and exits 0 when there are no errors;
+    `--strict` forces a nonzero exit if there are any warnings. Writes nothing.
+  - **Extended init/rebuild test-fixture filter.** In addition to
+    `tests`/`test`/`__tests__`, the filter now also drops assets whose
+    repo-relative root contains a `testdata`, `fixtures`, or `__fixtures__` path
+    SEGMENT (exact segment), catching leaks like
+    `internal/qualitygate/skillscan/testdata/skills/lark-demo`. `init`/`rebuild`
+    path only; the general discovery walk (`source add`) is untouched.
+  - **Key-aware legacy clone migration.** `getGlobalCacheDir()` migration of a
+    legacy `~/.skaile/sources/<bare-name>` clone now re-derives the clone's true
+    cache key from its `origin` remote and lands it at
+    `<cacheRoot>/sources/<host>/<owner>/<repo>` (was: preserved the bare name, so a
+    URL-keyed lookup missed it and it lingered mis-placed). Non-clone leftovers
+    (the sidecar remainder) are untouched. New `mergeLegacyEntriesKeyed` primitive
+    in `@skaile/workspaces/core`.
+
+  `publish` / `propose` / `yank` remain stubs (they need the store publish
+  endpoint).
+
+- [#343](https://github.com/skaile-ai/workspaces/pull/343) [`a8c2036`](https://github.com/skaile-ai/workspaces/commit/a8c2036e64c069ee46ebab3ff48e37044856b326) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix `skaile store login` — Keycloak device flow + correct store URL
+
+  The CLI's store auth was broken against the deployed store: the default URL
+  (`store.skaile.ai`) is dead and the old `/api/auth/*` login endpoints return 404.
+  `store login` now runs the Keycloak Device Authorization Grant (RFC 8628) against
+  `SKAILE_KEYCLOAK_URL` (default `https://auth.skaile.ai`, realm `skaile-store`,
+  public client `skaile-store-cli`) — it prints a URL + code to approve in a
+  browser, caches the token at `~/.skaile/auth.json` (shared with `store/cli`), and
+  refreshes transparently. The default store API URL is now `https://api.skaile.store`;
+  `whoami` reads `/api/v1/me`; every `/api/v1/*` publisher call authorizes with a
+  fresh device-flow token. Overridable via `SKAILE_STORE_URL` / `SKAILE_KEYCLOAK_URL`
+  / `SKAILE_STORE_REALM` / `SKAILE_STORE_CLI_CLIENT`.
+
+  Note: live login requires a public `skaile-store-cli` client (device-grant
+  enabled) registered on the store's Keycloak realm.
+
+### Patch Changes
+
+- [#332](https://github.com/skaile-ai/workspaces/pull/332) [`bd6e8f7`](https://github.com/skaile-ai/workspaces/commit/bd6e8f710e42017dc07afa4ab00f4134a28a038e) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Four CLI UX papercuts from hands-on testing:
+
+  - `skaile run "<prompt>"` no longer crashes with a raw `spawn omp ENOENT` when the
+    configured driver's binary is missing. The single-shot chat path now catches the
+    failure and prints the bridge's actionable hint (the binary is not installed /
+    not on PATH) plus a suggestion to try `--driver claude-sdk`; unrelated errors
+    still surface their own message and a non-zero exit.
+  - `skaile source add` warns about a missing `sha256` by pointing at the real
+    `skaile source manifest rebuild` command instead of the non-existent
+    `skaile source build-manifest --write`.
+  - `skaile source remove` (without `--purge`) now tells the user how to reclaim the
+    leftover clone — pass `--purge` or run `skaile cache clean`.
+  - `skaile install <ref>` (pointer-only global install) adds a clarifying line that
+    it installed globally under `~/.skaile/libraries/installed/`, and that
+    `skaile add <ref>` is how to deploy the asset into the current project.
+
+- [#328](https://github.com/skaile-ai/workspaces/pull/328) [`e613124`](https://github.com/skaile-ai/workspaces/commit/e613124bc6d5f1a46f01504a1fc239a0a905379f) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Preset UX polish from hands-on testing: `preset validate` no longer emits a
+  spurious "required" warning for a required placeholder with no default (that is
+  exactly what `export --redact` produces — required-ness is enforced at apply, not
+  validate); `skaile init` next-steps now suggests `preset apply`; and the apply
+  env-var hint points users to `.env`/shell (not skaile.yaml) so a first-time user
+  applying a shared preset knows where the secret value goes.
+
+- [#330](https://github.com/skaile-ai/workspaces/pull/330) [`be69fb8`](https://github.com/skaile-ai/workspaces/commit/be69fb816125478d7f1d2d1cc3fea8162d3f0875) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix `skaile search` so its store leg reaches the live catalog. The store half now
+  goes through the shared catalog client (tRPC to `skaile.store`) instead of the dead
+  `store.skaile.ai` REST endpoint, surfaces `catalog.url: local` and failures
+  non-silently, and prints copyable `kind:@publisher/name#version` refs for both store
+  and local results.
+
+- [#337](https://github.com/skaile-ai/workspaces/pull/337) [`b0acd87`](https://github.com/skaile-ai/workspaces/commit/b0acd87f3128946fd48a120afabf5cfe262c42ef) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Collapse per-asset missing-sha256 advisories into one summary line.
+
+  Since `source manifest init` stopped writing per-asset `sha256` for `root:`
+  entries, `skaile source add` / `source sync` printed one
+  `Missing sha256 — computed <hash> …` advisory line per asset. For a curated
+  overlay with dozens of assets that was pure noise.
+
+  Discovery now tags each absent-sha256 warning with a machine-readable
+  `code: "missing_sha256"` (on `ReferenceWarning`) instead of relying on the
+  message text, and `LocalCatalogSource.sync()` counts those and emits exactly
+  one collapsed advisory:
+  `<n> asset(s): sha256 not pinned — auto-computed locally (pin only for store publish)`.
+  All other advisories (e.g. unknown-kind ghost-install) still print individually.
+  The fatal `ManifestHashMismatch` path for a DECLARED-but-wrong sha256 is
+  unchanged.
+
+- [#336](https://github.com/skaile-ai/workspaces/pull/336) [`1d2cf89`](https://github.com/skaile-ai/workspaces/commit/1d2cf8905cd67bd5b568b046d6aff49d01cdc16d) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Sidecar polish — five papercut fixes for the `skaile source manifest` sidecar
+  authoring flow, found consuming `github.com/larksuite/cli`.
+
+  - **`init` no longer writes per-asset `sha256`.** The init writer emitted the
+    discovery `sha256` (computed over the FILTERED per-kind file set) on each
+    `root:` entry; `source add` then re-walked the WHOLE root dir → a different
+    file set → a different composite hash → `ManifestHashMismatch`, failing every
+    asset. `init` now omits `sha256` for `root:`-mode entries (a missing hash is a
+    non-fatal advisory), so `source add` on init output indexes cleanly with zero
+    hash mismatches.
+  - **`init` skips test-fixture directories.** Assets whose repo-relative `root`
+    contains a `tests` / `test` / `__tests__` path segment are dropped from the
+    generated manifest (conservative, not repo-specific) so fixture "skills"
+    (`scripts/*/tests/*`, `tests/cli_e2e/*`) don't pollute the curated inventory.
+    `init`-path only; the general discovery walk (`source add`) is untouched.
+  - **`init` next-step hint prints a runnable command; `edit` accepts the store
+    slug.** The hint now echoes the exact `<src>` the user passed (the URL) instead
+    of a bare short name that mis-expanded to the skaile-ai org. `resolveSourceArg`
+    additionally accepts the collision-free store slug (`<host>__<owner>__<repo>`)
+    as an identifier, matched against existing `~/.skaile/store/manifests/<arg>.yaml`
+    before bare-name expansion. Full-URL resolution still works.
+  - **`edit` respects a full `$EDITOR` command.** `EDITOR="code --wait"` now spawns
+    `code` with args `["--wait", <file>]` (was treated as one binary and failed).
+    New `resolveEditorCommand` splits the editor value on whitespace and appends
+    the target last; unset falls back to `vi`.
+  - **`preset export` warns on machine-local sidecar overlays.** When a captured
+    source resolves through a curated store manifest on this machine, export now
+    warns that those assets may not resolve elsewhere until the sidecar is shared.
+
+- [#333](https://github.com/skaile-ai/workspaces/pull/333) [`d213d69`](https://github.com/skaile-ai/workspaces/commit/d213d696e308f5253c618df359e8aa0625be7c8a) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Four asset-consume UX papercuts from hands-on testing (foreign repo shipping a
+  `skaile.manifest.yaml`, added via `skaile source add`, deployed via `skaile add`):
+
+  - **P-A — publisher `@` normalization.** A manifest declaring `publisher: '@acme'`
+    is now stored as `acme` (the leading `@` is the scope sigil the ref formatter
+    adds automatically). Previously it indexed as `@@acme` and the asset was
+    un-addable. Both manifest read paths are covered: `decodeSkaileManifest` (index
+    side, emits a `warning` diagnostic) **and** `resolveSourcePublisher` / `scanRepo`
+    (the `skaile search --local` scan/display side, which previously rendered the
+    copyable ref as `@@acme`). Only a single leading `@` is stripped; bare names are
+    untouched.
+  - **P-B — missing `sha256` is an advisory, not an indexing failure.** A manifest
+    asset with no `sha256` (and an unknown asset kind) now flows through the
+    discovery `warnings` channel and surfaces as an `advisory` on
+    `LocalCatalogSource.sync()` — never on `errors`. `skaile source add` /
+    `source sync` no longer report a false "N asset(s) failed to index" or exit 1
+    in this case; the asset is indexed and deployable, and the advisory is printed
+    on its own info line.
+  - **P-C — dead command pointer removed.** The missing-`sha256` advisory no longer
+    points at the not-wired `skaile source manifest rebuild` stub; it now reads
+    "only needed for store publish; auto-computed locally".
+  - **P-E — search kind-miss message.** `skaile search <kind>` with no matches now
+    says `No "<kind>" assets found in this project's sources.` instead of the
+    misleading never-synced `Run \`skaile source sync\` first` hint.
+
+## 1.4.0
+
+### Minor Changes
+
+- [#325](https://github.com/skaile-ai/workspaces/pull/325) [`a91d49c`](https://github.com/skaile-ai/workspaces/commit/a91d49cba353e1714e97faaa3fb7dde21a40304c) Thanks [@henkbla](https://github.com/henkbla)! - Protocol v3.4.0 — add the embedded-app capability source to the wire types.
+  `CapabilityOrigin` gains `{ kind: 'app'; appId: string }` and `Capability.side`
+  gains `'app'` ("the handler runs in the embedded app"). Both are additive and
+  ride through under the protocol's major-equality rule — a peer that does not
+  understand `origin:'app'` / `side:'app'` never produces or routes them, so
+  existing consumers (runner, bridge, platform) are unaffected until a source
+  actually registers an `app` capability. No new message types:
+  `capability_register` / `capability_invoked` / `capability_result` /
+  `capability_approve` / `render_invoked` are reused verbatim.
+
+  `PROTOCOL_VERSION` bumps to `3.4.0`. `isUserInvokable` defaults `app`-origin
+  capabilities to LLM-only (`false`) unless the author sets
+  `audience: ['llm','user']`. The `capability` log subkind now recognizes `app`
+  (with `appId` encoded into `instance` as `<appId>.<name>`).
+
+  Design: `packages/workspaces/_devlog/specs/2026-07-07-app-capability-source.md`.
+  This is the protocol keystone for Skailify (embedding agent-controllable apps in
+  Skaile sessions); the runner trust guard and platform-gateway routing land in
+  follow-up changes.
+
+- [#326](https://github.com/skaile-ai/workspaces/pull/326) [`8f5e6e6`](https://github.com/skaile-ai/workspaces/commit/8f5e6e6f0fe214df35418899e3eb8747fe10fc60) Thanks [@henkbla](https://github.com/henkbla)! - Extend the runner capability-registry origin-trust guard for the `app`
+  capability origin (protocol 3.4.0). `RegisterSource` gains an
+  `{ kind: 'app'; appId: string }` variant, and `CapabilityRegistry.register`
+  now enforces:
+
+  - an **app source** may declare `origin.kind: 'app'` **only for its own `appId`**;
+  - **no other source** (agent, client, skill, connector, mount, flow, mcp,
+    framework) may declare an `app` origin — the `agent` rule is tightened to
+    exclude `app` so a skill/connector/flow cannot impersonate an embedded app.
+
+  Violations are dropped with a warn-level log, exactly as origin mismatches are
+  today. This closes the forgery hole described in the app-capability-source spec
+  (§ Trust / forgery rule): without it a compromised source could register
+  `app.delete_everything` under a real app's id. The bare-string `'client'` /
+  `'agent'` sources and all existing origin rules are unchanged.
+
+  Also makes the registry fully `app`-aware in lock-step: `ORIGIN_PROMPT_ORDER`
+  and `CapabilityListFilter.side` gain `'app'`, so an `app`-origin capability's
+  `promptFragment` reaches the `<CAPABILITIES>` section and `list({ side: 'app' })`
+  is expressible. The authoritative per-connection `appId` binding is enforced at
+  the platform gateway (follow-up); this is the runner-side defence-in-depth.
+
+- [#327](https://github.com/skaile-ai/workspaces/pull/327) [`fc4ed2f`](https://github.com/skaile-ai/workspaces/commit/fc4ed2fa8945484a329f5c1f5f04d9a994cb9694) Thanks [@henkbla](https://github.com/henkbla)! - Add `@skaile/workspaces/app-sdk` — the thin SDK an embedded, agent-controllable
+  app uses to become a capability peer inside a Skaile session (the "Skailify"
+  embed-in-platform slice; protocol 3.4.0).
+
+  `createSkaileApp({ appId, transport })` opens an authenticated back-connection,
+  performs the app handshake (`app_hello` → `app_hello_ack` binding the session to
+  `appId`, or `app_hello_nack` refusal), registers `app.*` capabilities stamped
+  with `origin:{kind:'app', appId}` / `side:'app'`, and answers inbound
+  `capability_invoked` events by dispatching to the local handler and replying with
+  `capability_result` (a thrown handler / invalid input / unknown name rides back
+  as `{ error }`). Register / deregister mid-session is supported.
+
+  Also exports `defineAppCapability` (Zod-typed authoring that fixes `side:'app'`),
+  the `AppTransport` interface + app-channel message types, a browser-safe
+  `createWebSocketAppTransport` (injected session identity presented as the
+  `skaile-bearer.*` subprotocol the gateway already decodes), and an `AppLogger`.
+
+  Purely additive: a new subpath export; existing consumers are unaffected. No new
+  capability wire types — `capability_register` / `capability_invoked` /
+  `capability_result` are reused verbatim; only the `app_hello` handshake is
+  specific to this app↔gateway channel. Design:
+  `packages/workspaces/_devlog/specs/2026-07-07-app-capability-source.md`.
+
+- [#314](https://github.com/skaile-ai/workspaces/pull/314) [`d608fd9`](https://github.com/skaile-ai/workspaces/commit/d608fd9e7517662327d48123aad5a3ad080b1232) Thanks [@mortegro](https://github.com/mortegro)! - `FlowNode.type` now includes `"sub-flow"` and `"router"` alongside `"skill"` and
+  `"group"`, matching node kinds already shipped in production flows (e.g.
+  appbuilder-standard/-complex). `FlowNode.data` gained `flow` (delegated flow ID
+  for `sub-flow` nodes) and `routes` (ordered `{condition, target}` table for
+  `router` nodes). Consumers that previously cast around the narrower union can
+  drop those casts.
+
+  This is a type-level and documentation change only — the engine
+  (`computeFlowState`, `computeFlowStateFromSnapshots`, `computeSkippable`) still
+  tracks only `'skill'` nodes; `'sub-flow'` and `'router'` are excluded from
+  dependency computation the same as `'group'` today. See
+  `docs/flow-execution.md#node-types` for the full semantics of each kind and
+  what's intentionally left as downstream/future work.
+
+- [#317](https://github.com/skaile-ai/workspaces/pull/317) [`ca173c9`](https://github.com/skaile-ai/workspaces/commit/ca173c9e1617d45051a1d7fa21712660250fe13b) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Add `skaile preset apply <path>` — the consume half of the preset roundtrip. It reads a `.preset.yaml`, resolves placeholders, and writes the items back additively into the target project's `skaile.yaml` (the inverse of `preset export`). Bare-ref items become dependencies (deduped), `connector:<driver>` items become `ConnectorDeclaration`s, and `mcp:<id>` items become `McpServerDeclaration`s; a connector/mcp whose id already exists and differs is skipped (the user's config wins). Placeholder resolution is secret-safe: a `secret` placeholder resolves to an `env:<KEY>` reference (never the raw value) and the key is surfaced in a "set these env vars" summary, while non-secret `${INPUT:KEY}` tokens inline the provided literal (from `--input KEY=VAL`, an interactive prompt, or a declared default). Nested-preset refs are rejected for now. Unless `--no-deploy` is passed, the command runs the project install so new skill deps deploy. Flags: `--project-dir`, `--input` (repeatable), `--yes`, `--no-deploy`. Also adds `WorkspaceYamlEditor.addDependency` (dedupe) and `WorkspaceYamlEditor.setMcpServer` (add/replace-by-id) comment-preserving methods.
+
+- [#316](https://github.com/skaile-ai/workspaces/pull/316) [`9c2a7ab`](https://github.com/skaile-ai/workspaces/commit/9c2a7abea4076bb79ce22b9b38f3885b7d75a513) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Add `skaile preset export [name]` — snapshot a workspace's own `skaile.yaml` into a shareable `.preset.yaml`. Dependencies map to bare-ref items (copied verbatim), connectors to `connector:<driver>` items, and MCP servers to `mcp:<id>` items; `agent_config` is deliberately excluded as personal/machine-specific. The command has first-class secret safety: it scans connector/mcp config for inline credentials (anything that is not an `env:`/`forge:`/`secret:`/… reference), prints a loud summary, redacts flagged values into `${INPUT:…}` placeholders under `--redact` (or interactively on a TTY), and stamps a `CONTAINS INLINE SECRETS` header when any inline secret is left in place — so an export is never a silent success. Flags: `--project-dir`, `--out`, `--dir`, `--redact`, `--force`.
+
+- [#318](https://github.com/skaile-ai/workspaces/pull/318) [`c5c145c`](https://github.com/skaile-ai/workspaces/commit/c5c145ca06627da766b6df1471d626403daf3c0b) Thanks [@P1umPudding](https://github.com/P1umPudding)! - `skaile preset export`/`apply` now carry the **sources** a preset's dependencies resolve from, so a preset built against a non-factory git source (e.g. `skill:@mattpocock/grill-me` from `mattpocock/skills`) resolves on `apply` even in a workspace that never registered that source. Export captures only the needed sources — each dependency is matched to its lock entry by version-agnostic identity (kind+publisher+name) and the entry's `source.url` is recorded, excluding the bundled factory source; with no lock (or an unresolved dependency) it conservatively records every non-factory source. Apply registers those sources into `skaile.yaml` (deduped by url; an existing url with a differing pin is left untouched) before running install. Adds an optional `sources` field to the preset manifest schema and exports `FACTORY_SOURCE_URL` / `normalizeRepoUrl` from `@skaile/workspaces/asset-manager`.
+
+### Patch Changes
+
+- [#300](https://github.com/skaile-ai/workspaces/pull/300) [`5824f67`](https://github.com/skaile-ai/workspaces/commit/5824f671f3ca9c88adcebfe3584c03360f67e1b0) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix a hard crash in `skaile doctor`: `AssetManager.info()` now tolerates a bare
+  `kind:name` ref (publisher optional) instead of throwing "publisher required".
+  `doctor()` iterates `listDeployed()`, which — because it scans deploy dirs —
+  emits publisher-less refs; the strict parse in front of `info()`'s already
+  publisher-optional matching crashed on the first deployed asset. `info()` falls
+  back to a minimal tolerant parse and returns `null` when it can recover neither
+  a kind nor a name; the strict `parseAssetRef` is unchanged for other callers.
+
+- [#298](https://github.com/skaile-ai/workspaces/pull/298) [`80c9d58`](https://github.com/skaile-ai/workspaces/commit/80c9d5844f8c06a89769bc7c411b69c6a63eca9b) Thanks [@P1umPudding](https://github.com/P1umPudding)! - Fix `skaile install` never pruning manifest-less (content-sha pseudo-version)
+  assets. The install reconcile derived asset identity via `parseCanonicalLockKey`,
+  which rejected `#0.0.0-sha.<hash>` lock keys and returned `{}`, so a dependency
+  removed from `skaile.yaml` left its deployed files behind as a silent orphan.
+  `parseCanonicalLockKey` now falls back to parsing the bare identity when the pin
+  is a non-canonical pseudo-version — fixing the reconcile plus every other lock-key
+  consumer (locked-install restore, `list`/`globalState` state machine, `outdated`)
+  for manifest-less assets. `add`/`remove` now also keep `skaile.lock.yaml` in sync
+  so an added-then-removed asset can be reconciled away, and the reconcile warns on a
+  genuinely unparseable lock key instead of skipping it silently.
+
+- [#309](https://github.com/skaile-ai/workspaces/pull/309) [`f7dbdf3`](https://github.com/skaile-ai/workspaces/commit/f7dbdf341cf5f6aa6289d6d971a32183ac1cdcf3) Thanks [@mortegro](https://github.com/mortegro)! - `skaile source add` now clones/validates the repo **before** writing the source
+  entry to `skaile.yaml`. Previously the entry was persisted first, so a failed
+  clone (repo not found, bad URL, network error) — which hard-exits in
+  `ensureClone` — left a stale, un-cloned source recorded in `skaile.yaml`. The
+  entry is only written once the source is known-good.
+
+  A `--force` re-clone now moves the existing clone aside and only deletes it once
+  the fresh clone succeeds, so a failed re-clone restores the previous clone
+  instead of leaving the source registered with no cache behind it.
+
+- [#299](https://github.com/skaile-ai/workspaces/pull/299) [`f91a0dd`](https://github.com/skaile-ai/workspaces/commit/f91a0dd14f5775b76457c79f0d7ff68785fc3180) Thanks [@P1umPudding](https://github.com/P1umPudding)! - `skaile why <ref>` now distinguishes an undeclared ref from a declared-but-uninstalled one when the dependency chain is empty. Previously it always printed "not found in lock file. Run `skaile install` first." — misleading when nothing in `skaile.yaml` requires the ref, since install cannot help. Undeclared refs now get a clearer message pointing to `skaile list`; declared-but-uninstalled refs keep the install hint. The empty-chain decision is factored into a pure exported `whyEmptyMessage` helper.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -77,6 +77,6 @@ bun run cli run mvp         # run a flow
 ## Architecture Docs
 
 - [Client-Server Architecture](../../docs/client-server-architecture.md) — design for the agent client, transport, and shared state protocol (new packages: `client`, `transport`)
-- [Session Dispatcher Architecture](../../docs/session/architecture.md) — design for session message dispatching, persistence, and fan-out (new package: `session`)
+- [Session Dispatcher Architecture](../../docs/sections/session/architecture.md) — design for session message dispatching, persistence, and fan-out (new package: `session`)
 
 See each package's `CLAUDE.md` for architecture details and developer conventions.

package/dist/app-sdk/index.d.ts

@@ -0,0 +1,2 @@
+// Auto-generated by _scripts/emit-dts-sidecars.ts — do not edit by hand.
+export * from "./src/index.js";