@skaile/workspaces 5.9.0 → 5.11.0

package/dist/asset-manager/src/index.d.ts

@@ -32,6 +32,17 @@ export interface LibraryHolder {
     /** `true` for the holder `add <ref>` deploys. */
     picked: boolean;
 }
+/**
+ * One origin that holds a ref, see {@link AssetManager.refOrigins}: the bundled factory
+ * source, a project source clone, or a registered library.
+ */
+export interface RefOrigin {
+    kind: "factory" | "source" | "library";
+    /** `factory`, the source's short name, or the library name. */
+    label: string;
+    version: string;
+    description: string;
+}
 /**
  * Parse a canonical lock key (`<kind>:@<publisher>/<name>#<version>`) into its
  * parts. The lock key is a canonical asset ref, so this delegates to the one ref
@@ -68,6 +79,15 @@ export declare function softDepName(ref: string): string;
  * @internal Exported for unit tests; not part of the stable public surface.
  */
 export declare function parseRefTolerant(ref: string): AssetRef | null;
+/** A locked asset that now resolves from another library than its lock entry named. */
+export interface LibraryMove {
+    /** `kind:@publisher/name` (no version). */
+    ref: string;
+    /** Library name the lock entry recorded. */
+    from: string;
+    /** Library name the asset resolved from now. */
+    to: string;
+}
 /**
  * Reconciliation state of a declared dependency relative to the lock + disk.
  * `invalid` flags a `dependencies:` entry that isn't a parseable canonical ref —
@@ -193,6 +213,22 @@ export interface RepoStatusInfo {
     /** Error message when status check failed. */
     error?: string;
 }
+/** One deployed copy `install` made equal to its locked bytes again. */
+export interface RestoredAsset {
+    /** Canonical ref of the asset. */
+    ref: string;
+    /** Deployed files whose hand edit was overwritten (project-relative POSIX paths). */
+    restored: string[];
+    /** Files the asset does not ship that were deleted from its deployed directory. */
+    removed: string[];
+}
+/** One asset `install` moved from one locked version to another. */
+export interface ReplacedAsset {
+    /** `kind:@publisher/name`, no version. */
+    ref: string;
+    from: string;
+    to: string;
+}
 /**
  * Result of a full `skaile install` or `skaile add` run.
  *
@@ -208,9 +244,9 @@ export interface InstallResult {
      * non-locked path every entry is a bare ref; the reason a miss happened lives in
      * {@link InstallResult.missingHints}. The `--locked` path still appends its prose
      * (`ref (not found in library "x")`) to the entry, and also lists every
-     * {@link AssetManager.lockGaps} gap (a declared dependency or a locked asset's
-     * `requires` with no lock entry, a lock that contradicts a `skaile.yaml` pin) as its
-     * one-line message.
+     * {@link AssetManager.projectState} gap (a declared dependency or a locked asset's
+     * `requires` with no lock entry, a lock that contradicts a `skaile.yaml` pin, a library
+     * that cannot supply a locked asset) as its one-line message.
      */
     missing: string[];
     /**
@@ -228,6 +264,24 @@ export interface InstallResult {
      * content. A re-lock can happen with nothing to deploy. Absent when none changed.
      */
     relocked?: string[];
+    /**
+     * Library-origin assets whose lock entry now names another library than before. `install`
+     * keeps a locked asset on its library; only `update`, a pin, or a locked library that no
+     * longer holds the asset moves it. Absent when none moved.
+     */
+    moved?: LibraryMove[];
+    /**
+     * Assets whose locked version `install` replaced with another version of the same asset
+     * (`ref` is `kind:@publisher/name`). Not part of {@link InstallResult.removed}: nothing
+     * left the project. Absent when none changed.
+     */
+    replaced?: ReplacedAsset[];
+    /**
+     * Deployed copies `install` made equal to their locked bytes again: a file edited by hand
+     * (`restored`) or an extra file in the asset directory (`removed`), both as project-relative
+     * POSIX paths. Absent when every deployed copy already matched.
+     */
+    restored?: RestoredAsset[];
     /** Whether `skaile.lock.yaml` was written or updated. */
     lockWritten: boolean;
     /**
@@ -259,6 +313,11 @@ export interface InstallResult {
      * `skaile.yaml` (only files an earlier `skaile install` rendered are ever removed).
      */
     agentFilesRemoved?: string[];
+    /**
+     * Agent instances of `skaile.yaml` whose `ref` resolves to no agent (never added, or gone):
+     * one message each. Their earlier rendering is kept. `skaile install` fails on a non-empty list.
+     */
+    agentInstanceErrors?: string[];
 }
 /**
  * An installed asset whose source repository is behind the remote.
@@ -283,7 +342,7 @@ export interface OutdatedEntry {
     /**
      * Set when the locked asset cannot be checked or is not in place: its library is
      * not registered (renamed or removed), its deployed copy is gone, or the lock does not
-     * cover it ({@link AssetManager.lockGaps}). Such a row has no `latestVersion`.
+     * cover it ({@link AssetManager.projectState}). Such a row has no `latestVersion`.
      */
     problem?: string;
     /**
@@ -307,6 +366,8 @@ export interface OutdatedEntry {
  * - `not-deployed` — the asset resolves, but there is no deployed copy to compare.
  * - `identical` — the deployed copy matches the source.
  * - `differs` — the deployed copy differs; `diff` carries the unified diff.
+ * - `no-files` — the asset kind has no files of its own (a preset: its items are the assets to
+ *   compare) and the lock records it.
  *
  * @docLink packages/asset-manager/concepts#asset-manager
  */
@@ -316,6 +377,8 @@ export type DiffResult = {
     status: "not-deployed";
 } | {
     status: "identical";
+} | {
+    status: "no-files";
 } | {
     status: "differs";
     diff: string;
@@ -337,6 +400,14 @@ export interface RemoveResult {
     changed: boolean;
     /** Canonical refs (`kind:@publisher/name`) of the orphaned dependencies dropped as well. */
     pruned: string[];
+    /**
+     * Set when the removal was refused because other assets still require it; nothing was
+     * removed. `ref` is the asset (`kind:@publisher/name`), `requiredBy` the refs requiring it.
+     */
+    blocked?: {
+        ref: string;
+        requiredBy: string[];
+    };
 }
 /**
  * A missing dependency detected by `AssetManager.doctor()`.
@@ -367,21 +438,35 @@ export interface DepIssue {
     fix?: string;
 }
 /**
- * One way the lock fails to cover or match the project; see {@link AssetManager.lockGaps}.
+ * One way the project differs from what it declares and locks; see {@link AssetManager.projectState}.
  *
  * @docLink packages/asset-manager/concepts#asset-manager
  */
 export interface LockGap {
-    type: "declared" | "invalid" | "drift" | "pin" | "requires" | "unresolved";
-    /** The ref to act on: the declared ref, the unmet dependency `kind:name`, or the unresolvable asset. */
+    type: "declared" | "invalid" | "drift" | "pin" | "requires" | "unresolved" | "library" | "incomplete" | "content" | "modified" | "agent";
+    /** The ref to act on: the declared ref, the unmet dependency `kind:name`, or the asset itself. */
     ref: string;
-    /** What is wrong, as a phrase that follows `ref` (e.g. `is declared but does not resolve — run …`). */
+    /** Set on a `requires` gap: the requiring asset, `kind:@publisher/name` (`kind:name` when the lock knows no publisher). */
+    asset?: string;
+    /** What is wrong, as a phrase that follows `ref` (e.g. `is declared but not locked — run …`). */
     reason: string;
     /** One line naming the gap, without a leading status mark: `${ref} ${reason}`, except a `requires` gap, which leads with the requiring asset. */
     message: string;
     /** Set when `skaile install` cannot fix the gap; `reason` then names what to change instead. */
     manualFix?: true;
 }
+/**
+ * The project's state as {@link AssetManager.projectState} computes it: the one verdict
+ * `check`, `doctor`, `outdated`, `diff` and `install --locked` share.
+ *
+ * @docLink packages/asset-manager/concepts#asset-manager
+ */
+export interface ProjectState {
+    /** Every problem, one {@link LockGap} each; empty when the project is as declared and locked. */
+    gaps: LockGap[];
+    /** What {@link AssetManager.doctor} found: the unmet requirements (a `doctor` table row each) and the locked assets nothing provides. */
+    requirements: DepIssue[];
+}
 /**
  * A single deployed asset shown in the workspace overview.
  *
@@ -481,8 +566,9 @@ export interface AssetManagerOptions {
      */
     indexPath?: string;
     /**
-     * Receives the warning printed when one ref is held by several local
-     * libraries (which library was chosen and why). Defaults to `console.warn`
+     * Receives the warning printed when {@link AssetManager.add} picks one ref out of several
+     * local libraries (which library was chosen and why); no other method warns. Defaults to
+     * `console.warn`
      * with a `skaile:` prefix. A CLI with a live spinner passes a collector and
      * prints the lines after the spinner stops, so frames can't overwrite them.
      */
@@ -596,8 +682,8 @@ export declare class AssetManager {
      * Render every agent instance of `skaile.yaml` into the driver target's native
      * agent files (`.claude/agents/<id>.md`, …) and prune the renderings of
      * instances that left the config. Runs after the skills deploy, so composed
-     * skills resolve. Project scope only. Never fails an install — a render error
-     * is warned and swallowed.
+     * skills resolve. Project scope only. An instance whose `ref` resolves to no agent is
+     * reported in `agentInstanceErrors`; any other render error is warned and swallowed.
      */
     private renderAgentInstances;
     private loadConfig;
@@ -625,6 +711,11 @@ export declare class AssetManager {
      *
      * @param opts.quiet - Skip the cross-library collision warning (a lookup that only
      *   builds an error hint must not warn).
+     * @param opts.library - Resolve only from this library (the one a lock entry names), not
+     *   from every registered one. Never warns: no choice is made between libraries.
+     * @param opts.lockedLibraries - `kind:publisher/name` → the library its lock entry names
+     *   ({@link AssetManager.lockedLibraryNames}). A ref listed here resolves from that library
+     *   when it holds a match, whatever the default library is.
      * @returns the matched deploy entries, the set of `missing` refs covered, and
      *   each entry's originating library name.
      */
@@ -647,10 +738,47 @@ export declare class AssetManager {
      * @returns `kind:@publisher/name` → holders; refs held by one library are absent.
      */
     libraryHolders(): Promise<Map<string, LibraryHolder[]>>;
+    /**
+     * Every asset a registered library holds, read from the library directories themselves
+     * (not the local index, which keeps one row per ref and version and loses a ref when
+     * another library re-publishes it). One row per holder, all versions.
+     *
+     * @returns `[]` when no library holds an asset. Never warns.
+     */
+    libraryAssets(): Promise<Array<{
+        entry: CatalogEntry;
+        library: string;
+    }>>;
+    /**
+     * Every origin that holds `ref` (`kind:@publisher/name`) with the version it holds, in
+     * the order `add <ref>` prefers them, so the first row is the one `add` deploys: the
+     * project's source clones and the bundled factory source (highest version first), then
+     * the registered libraries. `add`, `info` and `search` all read this, so the three name
+     * one origin for one ref. Stores are not asked (no network).
+     *
+     * @returns one row per origin and version; `[]` for a ref without a publisher or one
+     *   nothing holds. Never warns.
+     */
+    refOrigins(ref: string): Promise<RefOrigin[]>;
+    /**
+     * Every ref (`kind:@publisher/name`) that several origins hold at different versions,
+     * with its origins in {@link refOrigins} order. A ref the origins hold at one version
+     * has nothing to choose between and is left out.
+     */
+    competingOrigins(): Promise<Map<string, RefOrigin[]>>;
+    /**
+     * The origins of {@link refOrigins} for every ref, or for the one `only` names
+     * (`kind:@publisher/name`), keyed by `kind:@publisher/name`.
+     */
+    private collectOrigins;
     /**
      * Where each missed publisher-qualified ref went when its publisher changed, for every
      * ref at once (one library scan, one lock read):
-     * - `moved` when a registered library holds the same kind + name under another publisher;
+     * - `moved` when a registered library holds the same kind + name under another publisher.
+     *   When the lock ties the missed ref to a library, only that library is looked at (an
+     *   asset of the same name in another library is a different asset). Without a lock
+     *   entry, a library asset the project already declares or locks under its own ref is
+     *   not offered, and two candidate publishers are ambiguous: no hint;
      * - `lockedAs` when the lock holds the same kind + name under another publisher, records
      *   the library it came from, and that library now holds the asset under yet another
      *   publisher than the locked one. An unrelated asset that merely shares kind + name does
@@ -716,8 +844,34 @@ export declare class AssetManager {
      * preferring it would lock a stale version after an in-place bump. The hash is
      * computed from the files on disk, so it matches what `install --locked`
      * re-hashes.
+     *
+     * A git-backed library also records its remote URL. When the previous lock names the
+     * library under another name that {@link lockedLibrary} matched to this one by URL (a
+     * teammate registered the same remote under a different name), the entry keeps the locked
+     * name and URL: the lock does not change because it was installed on another machine.
      */
     private libraryLockEntries;
+    /**
+     * Lock keys that `skaile.yaml` still wants: the entries a declared ref names, plus every
+     * entry such an asset requires, transitively. All keys when a `preset:` is declared.
+     */
+    private declaredLockKeys;
+    /**
+     * The `Missing:` lines of every library-origin lock entry whose library cannot supply
+     * assets on this machine (not registered, or registered with its directory gone). Plain
+     * `install` stops on a non-empty list, the same lines `install --locked` prints: it must
+     * not re-resolve a locked asset from another origin. The ONE function that decides "the
+     * locked library is not here", so a lock-recorded URL fallback extends it in one place.
+     *
+     * Only entries `skaile.yaml` still declares, or that a declared asset requires
+     * (transitively, read from the deployed copy), count. A stale entry nothing declares is
+     * pruned by `install` as usual, so a removed dependency whose library is gone can be
+     * cleaned up. With a declared `preset:` every entry counts: the lock records no edge
+     * from a preset to its items, and the preset's own library may be the one that is gone.
+     *
+     * @param declared - The `dependencies:` refs as written in `skaile.yaml`.
+     */
+    private unavailableLockedLibraries;
     /**
      * Re-resolve every library-origin lock entry from its named library, for
      * `install --locked`. An entry is restored only when its library is still
@@ -726,10 +880,41 @@ export declare class AssetManager {
      */
     private restoreLibraryLockEntries;
     /**
-     * On-disk root of the library named `name`: the registered path from the index
-     * when it exists, else `<libraries dir>/<name>`; `null` when neither is a directory.
+     * Whether a deployed copy exists for the lock entries `install` kept for the unresolved
+     * `ref`. A kind with no install target has no deployed copy.
      */
+    private keptCopyDeployed;
+    /**
+     * How the library `origin` names stands on this machine. THE one lookup of a locked library
+     * ("is it registered here?"): `check`, `outdated`, `install` and `install --locked` all ask it.
+     *
+     * - registered in the index under its name: `ok` at its registered path, or `dir-missing` when
+     *   that directory is gone;
+     * - not registered: a directory `<libraries dir>/<name>` nobody unregistered still counts as a
+     *   hand-made library (`ok`). One `library remove` unregistered without `--purge` does not
+     *   (it stays on disk but no longer resolves), and neither does the reserved `installed` folder.
+     * - otherwise, when the lock recorded the library's remote URL: another registered library
+     *   whose git remote is the same repository (`.git` suffix, trailing `/` and the
+     *   `git@host:o/r` / `https://host/o/r` forms do not matter) and whose directory exists is
+     *   `ok`, with `name` set to the name it is registered under here. The library name is
+     *   machine-local; the remote is what a clone shares.
+     */
+    private lockedLibrary;
+    /** On-disk root of the library `origin` names; `null` unless {@link lockedLibrary} says `ok`. */
     private libraryPath;
+    /**
+     * Where each library-origin lock entry of this project resolves on this machine: identity
+     * `kind:publisher/name` (no scope sigil, no version) → the name the locked library is
+     * registered under here. The name differs from the locked one when the lock's remote URL
+     * matched another registered library ({@link lockedLibrary}). A deployed entry whose library
+     * resolves nowhere (not registered, directory gone) maps to `null`.
+     *
+     * Direct `asset install` entries (`library.installed`) are included and resolved the same
+     * way, but they map to the locked library name when that lookup fails: such a copy sits in
+     * the project and does not depend on the library still being registered. A missing or
+     * unreadable lock yields an empty map. `skaile manage` uses it to tick the right library row.
+     */
+    lockedLibraryNames(): Promise<Map<string, string | null>>;
     /** A candidate's stable identity key (`<publisher>/<kind>:<name>@<version>`). */
     private candidateKey;
     /**
@@ -819,11 +1004,15 @@ export declare class AssetManager {
      * @param opts.link - When `true`, symlink local-path assets instead of copying them
      *   (the author dev-loop). Machine-local / not for committing; a no-op for
      *   store/factory sources. Defaults to copy.
+     * @param opts.moveLibraries - When `true` (`skaile update`), a locked library asset is
+     *   re-resolved from every library and may move to another one; {@link InstallResult.moved}
+     *   lists the moves. Without it a locked asset stays on the library its lock entry names.
      * @returns {@link InstallResult} summarising what was deployed, what was missing, and any collisions.
      */
     install(opts?: {
         locked?: boolean;
         link?: boolean;
+        moveLibraries?: boolean;
     }): Promise<InstallResult>;
     /**
      * Extend `kept` (see {@link keptLockEntries}) with every previous lock entry a kept asset
@@ -833,8 +1022,13 @@ export declare class AssetManager {
      * cannot be read has no known requirements.
      */
     private keepRequiredByKept;
-    /** Publisher-qualified refs the deployed copy of the asset behind lock `key` requires. */
-    private deployedRequirements;
+    /**
+     * Publisher-qualified refs the deployed copy of `id` requires, read from its own
+     * manifest file (`metadata.requires`, a manifest `dependencies:` entry): the one place
+     * the requirements stay knowable when no source or library holds the asset any more.
+     * A copy that is not deployed or cannot be read has no known requirements.
+     */
+    private deployedRequirementsOf;
     /**
      * Ensure all source clones are present/up to date. Returns an early
      * {@link InstallResult} describing the failed source on the first error, or
@@ -873,7 +1067,29 @@ export declare class AssetManager {
      *   to pull every connector's deps). Future: add a flag to opt in.
      */
     private installRuntimeAssetDeps;
+    /**
+     * Give every ref `install` could not resolve, and that has no hint yet, the fix the shared
+     * {@link AssetManager.projectState} names for it (a declared ref no library or source holds,
+     * a requirement nothing holds). Runs after the deploy, so a requirer is known by then.
+     * Mutates `hints`: ` <reason>` follows the ref in the `Missing:` line.
+     */
+    private adviseMissing;
     private installLocked;
+    /**
+     * Parse the ref `add` was given. A ref the grammar rejects fails with the parser's message
+     * minus its manifest-migration advice (it points at a skill that is not for `add`), and:
+     * - a publisher-less ref (`report-html`, `skill:report-html`) names the assets of that
+     *   kind and name that `add` can resolve (a source, the bundled factory source or a
+     *   library holds them), so `Did you mean` never names an asset that does not resolve;
+     * - a `@version` suffix (`skill:@acme/x@1.0.0`) says the pin is written `#<version>`.
+     */
+    private parseAddRef;
+    /**
+     * The publisher-qualified refs of the assets named like the publisher-less `ref` that
+     * `add` resolves: held by a source clone, the bundled factory source or a registered
+     * library. A ref without a kind means a skill, as the grammar says.
+     */
+    private resolvableMatches;
     /**
      * Add a single asset (and its transitive dependencies) to the workspace.
      *
@@ -887,6 +1103,8 @@ export declare class AssetManager {
      *   store/factory sources. Defaults to copy.
      * @param opts.onLibraryOrigin - Called once per deployed library-origin asset with its
      *   canonical ref and the name of the library it was resolved from.
+     * @param opts.onLibraryMoved - Called once per asset whose lock entry named another library
+     *   than the one this add resolved it from.
      * @param opts.onPresets - Called once with the presets expanded into this add (the
      *   added preset and any it nests); a library-held preset names its library.
      * @returns Array of asset refs that were deployed in this call.
@@ -896,7 +1114,13 @@ export declare class AssetManager {
     add(ref: string, opts?: {
         link?: boolean;
         onLibraryOrigin?: (deployedRef: string, library: string) => void;
+        /** Called per already-locked asset this add moved to another library than its lock entry named. */
+        onLibraryMoved?: (move: LibraryMove) => void;
         onPresets?: (presets: PresetExpansion[]) => void;
+        /** Called per symlink an asset's copy deploy leaves out (`ref`, path under the asset dir). */
+        onSkippedSymlink?: (ref: string, path: string) => void;
+        /** Called per `.env` file in an asset's directory that a copy deploy leaves out. */
+        onEnvFile?: (ref: string, path: string) => void;
     }): Promise<string[]>;
     /**
      * Report the body-link **soft dependencies** of the given assets that are not
@@ -1039,10 +1263,16 @@ export declare class AssetManager {
      * preset's items count as its requirements. They are undeployed and unlocked;
      * a dependency still declared or required elsewhere stays.
      *
+     * An asset another locked asset (or a declared preset) requires is kept and reported in
+     * `blocked`, nothing changes, unless `opts.force` (see {@link requiredByOthers}).
+     *
      * @returns `changed` as {@link remove}; `pruned` the canonical refs
-     *   (`kind:@publisher/name`) of the dependencies dropped as well.
+     *   (`kind:@publisher/name`) of the dependencies dropped as well; `blocked` when the
+     *   removal was refused.
      */
-    removeWithDependencies(ref: string): Promise<RemoveResult>;
+    removeWithDependencies(ref: string, opts?: {
+        force?: boolean;
+    }): Promise<RemoveResult>;
     /**
      * Resolve the identity {@link remove} acts on. A publisher-qualified ref is taken
      * as written; a short ref (`kind:name`, or just `name`) is matched on kind + name
@@ -1053,6 +1283,21 @@ export declare class AssetManager {
      * @throws On a malformed ref, or when a short ref matches more than one asset.
      */
     private resolveRemoveTarget;
+    /**
+     * The reverse guard of {@link removeWithDependencies}: which other locked assets (and
+     * declared presets) require `target`. Their requirements are read the way {@link lockedGraph}
+     * reads them for pruning. Never touches the project.
+     *
+     * @returns `ref` and `requiredBy` (both `kind:@publisher/name`, version-agnostic), or `null`
+     *   when `target` is not locked or nothing else requires it.
+     */
+    private requiredByOthers;
+    /**
+     * Publishers under which the lock or `skaile.yaml` track `kind:name`. A deployed dir carries
+     * no publisher, so this is what says whose copy it is. `undefined` stands for a
+     * publisher-less declaration.
+     */
+    private trackedPublishers;
     /** Undeploy `parsed` from every target harness and drop its declaration and lock entry. */
     private removeResolved;
     /**
@@ -1238,6 +1483,14 @@ export declare class AssetManager {
      *   instead. `[]` when the asset is not in the lock file.
      */
     why(ref: string): Promise<string[]>;
+    /**
+     * The {@link AssetManager.why} chain of a preset. A preset is never a lock asset: its record
+     * is the lock's `presets` slice. Declared in `skaile.yaml` it is `direct`; one only a declared
+     * preset nests is traced through the presets that list it.
+     *
+     * @returns `[]` when the lock does not record the preset.
+     */
+    private whyPreset;
     /**
      * List installed assets that have a newer upstream available.
      *
@@ -1248,20 +1501,33 @@ export declare class AssetManager {
      * - **Library assets** — a library-origin lock entry whose library files on disk
      *   (not the index, which lags until `skaile library index`) hold a newer version
      *   than the locked one (`latestVersion`, `library` set), or the same version with
-     *   different bytes (`contentChanged`). `behind` is 0. An unregistered library is a
-     *   `problem` row.
-     * - **Lock gaps** — every {@link AssetManager.lockGaps} gap (a declared dependency or a
-     *   deployed asset's `requires` with no lock entry, a lock that contradicts a
-     *   `skaile.yaml` pin) as a `problem` row, so `outdated` agrees with `check`.
+     *   different bytes (`contentChanged`). `behind` is 0.
+     * - **Project state** — every {@link AssetManager.projectState} gap (an unregistered or
+     *   renamed library, a missing deployed copy, a declared dependency or a deployed asset's
+     *   `requires` with no lock entry, a lock that contradicts a `skaile.yaml` pin) as a
+     *   `problem` row, so `outdated` lists what `check`, `doctor` and `install --locked` fail
+     *   on. An asset that also has a version row is listed once, with that row.
      *
      * @returns Array of {@link OutdatedEntry} objects.
      */
     outdated(): Promise<OutdatedEntry[]>;
     /**
-     * Append one `problem` row per {@link AssetManager.lockGaps} gap whose asset is not
-     * listed yet, so `outdated` reports the same set `check` and `install --locked` fail on.
+     * Add one `problem` row per {@link AssetManager.projectState} gap whose asset is not
+     * listed yet, so `outdated` lists the same assets `check`, `doctor` and `install --locked`
+     * fail on. An asset that is behind its source and also broken is listed once, with its
+     * version row.
      */
     private addLockGapRows;
+    /**
+     * The deploy entry of a library-origin asset from the library its lock entry records,
+     * at the locked version when that library still holds it (else its newest). Other
+     * libraries holding the same ref are not consulted: the lock already chose.
+     *
+     * @param want - Kind, name and optional publisher of the asset.
+     * @returns `null` when the lock has no library-origin entry for it, or the recorded
+     *   library is gone or no longer holds it (callers fall back to a general lookup).
+     */
+    private lockedLibraryEntry;
     /**
      * Produce a unified diff from the deployed asset to its catalog source: `-` lines
      * are in the deployed copy only (local edits `update` would overwrite), `+` lines
@@ -1341,24 +1607,114 @@ export declare class AssetManager {
      */
     doctor(): Promise<DepIssue[]>;
     /**
-     * Everything the lock does not cover or contradicts, in one list: the set
-     * `skaile check`, `skaile install --locked` and `skaile outdated` all report.
+     * The project's state as one verdict: every way the project differs from what it
+     * declares and locks. `skaile check`, `skaile doctor`, `skaile outdated`, `skaile diff`
+     * and `skaile install --locked` all take their verdict and exit code from this one list,
+     * so one situation reads the same in all five.
      *
      * - `declared` — a `skaile.yaml` dependency with no lock entry (library or source gone,
      *   unresolvable ref, never installed);
      * - `invalid` — a `dependencies:` entry that is not a parseable ref;
-     * - `drift` — declared + locked but its deployed files are missing;
+     * - `drift` — a locked asset whose deployed files are missing;
      * - `pin` — a declared `#pin` that no lock entry for that asset satisfies;
-     * - `requires` — a deployed asset's `requires` that is not deployed (so not locked either);
-     * - `unresolved` — a lock-managed asset that no source or library holds any more.
+     * - `requires` — a deployed asset's `requires` (or a declared preset's item) that is not
+     *   deployed (so not locked either);
+     * - `unresolved` — a lock-managed deployed asset that no source or library holds any more;
+     * - `library` — a locked library asset whose library is not registered (renamed or
+     *   removed) or no longer holds it, while another library holds it now;
+     * - `incomplete` — a deployed library asset that lacks files of its library entry;
+     * - `content` — a locked library asset whose files in the library changed since the lock
+     *   (or whose lock hash predates the one shared asset hash); `skaile install` re-locks it;
+     * - `agent` — an `agents.<id>.ref` (or `agent.definition`) that binds to no agent.
+     *
+     * An asset appears once for what the lock says about it (`unresolved`, else `library`,
+     * else `drift`). A declared ref no registered library or source holds names
+     * `skaile library init` / `skaile remove`, never `skaile install`: `install` has nothing
+     * to resolve it from.
      *
-     * Project mode only: a global manager (`global: true`) returns `[]`. A project without
-     * `skaile.yaml` has no declared set, so only the `requires` / `unresolved` gaps of
-     * deployed assets can appear.
+     * Project mode only: a global manager (`global: true`) has no gaps. A project without
+     * `skaile.yaml` has no declared set, so only the lock and deployed-asset gaps can appear.
      *
-     * @returns One {@link LockGap} per gap; empty when the lock covers everything declared.
+     * @returns The {@link ProjectState}; `gaps` is empty when the project is as declared and locked.
      */
+    projectState(): Promise<ProjectState>;
+    /**
+     * Why the `agent:` ref of agent instance `id` binds to nothing, as the phrase that follows
+     * the ref in a {@link LockGap}; see {@link AssetManager.unboundAgentAdvice}.
+     */
+    private unboundAgentReason;
+    /**
+     * What is wrong with an `agent:` ref bound by an agent instance and what to do (`lead`, then
+     * `advice`). `skaile add` is named only when a registered library or source holds the agent
+     * and `add` takes the ref (it needs a publisher); otherwise the user registers the library
+     * that holds it, writes the publisher, or drops the binding.
+     */
+    private unboundAgentAdvice;
+    /** @deprecated Use `(await projectState()).gaps`; removed in the next major. */
     lockGaps(): Promise<LockGap[]>;
+    /**
+     * The {@link ProjectState} gaps that name `ref`: as the gap's own ref, or as the asset
+     * whose requirement is unmet. A ref without a publisher matches any publisher.
+     *
+     * @param ref - Asset ref in `kind:name` or `kind:@publisher/name` form.
+     */
+    gapsOf(ref: string): Promise<LockGap[]>;
+    /**
+     * Locked library assets whose library cannot supply them: the library is not registered
+     * (renamed or removed) or no longer holds the asset. Another library holding it makes the
+     * gap fixable by `skaile install` (it re-locks); otherwise the user registers the library
+     * again or drops the dependency.
+     *
+     * @param named - `kind:name` identities already reported; they are skipped.
+     */
+    private libraryOriginGaps;
+    /**
+     * The {@link RestoredAsset} rows for the drifted copies (see {@link lockedCopyDrift}) a
+     * deploy just wrote again: those whose ref is among the `deployed` canonical refs.
+     */
+    private restoredCopies;
+    /**
+     * Locked assets whose deployed copy differs from the bytes the lock covers: a file edited by
+     * hand, or a file the asset does not ship. One row per asset, `ref` being `kind:@publisher/name`
+     * and `key` its lock key. The one comparison behind the `modified` gap and the `Restored` lines
+     * of `install`.
+     *
+     * - A library-origin asset is compared with its library's files, but only while those equal the
+     *   locked hash (changed library content is the `content` gap's business), both modified and
+     *   extra files.
+     * - A source asset is compared with the per-file hashes the lock records (modified files only:
+     *   the lock lists what the source covers, not what the deploy copies).
+     *
+     * An agent (rendered, not copied), a `--link` deploy, an asset with a configured patch, and a
+     * copy that is missing are not compared: other gaps cover them. Project mode only.
+     */
+    private lockedCopyDrift;
+    /**
+     * Locked assets (declared or required by one) whose deployed copy is gone: `skaile install`
+     * restores them. Same deployability rule as {@link AssetManager.listDeclared}'s `drift`.
+     *
+     * @param named - `kind:name` identities already reported; they are skipped.
+     */
+    private undeployedLockGaps;
+    /**
+     * The `skaile.yaml` side of {@link AssetManager.projectState}: declared refs that do not
+     * parse, never resolved into the lock, are not materialized, or contradict a `#pin`.
+     * A project with no (or an unreadable) `skaile.yaml` has no declared set to reconcile.
+     *
+     * @param requirements - What {@link AssetManager.doctor} found; a declared preset whose
+     *   items it already named needs no second line.
+     * @param named - `kind:name` identities already reported; a declared asset among them
+     *   needs no `drift` line.
+     */
+    private declaredGaps;
+    /** Whether the lock's `presets` slice records `want` (kind, name and, when both carry one, publisher). */
+    private presetRecorded;
+    /**
+     * Whether `skaile install` can resolve a declared ref: a source or library holds it, or the
+     * project declares a store that may. The global catalog is not asked: a check never goes
+     * to the network.
+     */
+    private declaredRefResolvable;
     /**
      * Items of each declared `preset:` dependency that the lock does not cover.
      *
@@ -1456,6 +1812,15 @@ export declare class AssetManager {
      * @returns `true` when a declaration was removed.
      */
     private removeDependencyFromConfig;
+    /**
+     * Drop the agent instances of `skaile.yaml` (`agents.<id>`, or the `agent.definition`
+     * default) whose `ref` binds to `target`, and the native agent files an install rendered for
+     * them. Only an `agent` target has bindings; project mode only. A `ref` without a publisher
+     * matches any publisher, and a pin is ignored.
+     *
+     * @returns `true` when a binding was removed.
+     */
+    private removeAgentBindings;
     private resolveRepoDir;
 }
 export { installAgent } from "./install-agent.js";