@delorenj/skillex 0.2.0 → 0.3.1

package/dist/commands/clients.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+import type { ResultEnvelope } from "../core/result.js";
+interface Output {
+    emit(result: ResultEnvelope<unknown>, text?: string): void;
+    help(command: Command): void;
+}
+export declare function registerClientCommands(program: Command, output: Output): void;
+export {};

package/dist/commands/integrations.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+import type { ResultEnvelope } from "../core/result.js";
+interface Output {
+    emit(result: ResultEnvelope<unknown>, text?: string): void;
+    help(command: Command): void;
+}
+export declare function registerIntegrationCommands(program: Command, output: Output): void;
+export {};

package/dist/commands/roots.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from "commander";
+import type { ResultEnvelope } from "../core/result.js";
+interface Output {
+    emit(result: ResultEnvelope<unknown>, text?: string): void;
+    help(command: Command): void;
+}
+export declare function registerRootCommands(program: Command, output: Output): void;
+export {};

package/dist/core/activation-types.d.ts

@@ -9,7 +9,8 @@ export interface OwnedNode {
     readonly children?: Readonly<Record<string, EntryIdentity>>;
 }
 export interface SourceRevision {
-    readonly kind: "catalog" | "pack";
+    /** Legacy receipts recorded "pack" for whole-root pack sources; they stay readable. */
+    readonly kind: "catalog" | "pack" | "set";
     readonly path: string;
     readonly commit: string | null;
     readonly reason: string | null;

package/dist/core/catalog-write.d.ts

@@ -15,6 +15,11 @@ export interface CatalogWriteResult {
 }
 export interface CatalogWriteOptions extends RegistryOptions, CatalogLockOptions {
     readonly dryRun?: boolean;
+    /**
+     * Override the receipt's imported_from label, e.g. a sanitized Git URL
+     * instead of an ephemeral clone path, so provenance outlives the clone.
+     */
+    readonly importedFrom?: string;
 }
 export interface CreateSkillOptions extends CatalogWriteOptions {
     readonly description?: string;

package/dist/core/client-isolation.d.ts

@@ -0,0 +1,74 @@
+import { type ResultEnvelope } from "./result.js";
+import type { ResolveOptions } from "./selection.js";
+export interface ClientIsolationOptions extends Omit<ResolveOptions, "scope" | "inheritGlobal"> {
+    readonly client?: string;
+    readonly apply?: boolean;
+    readonly dryRun?: boolean;
+    /** Explicitly permit the project block to override shared user permissions, never agent rules. */
+    readonly overridePermissions?: boolean;
+    readonly stateHome?: string;
+    readonly timeoutMs?: number;
+}
+export interface ClientVerifyOptions extends Omit<ClientIsolationOptions, "apply" | "dryRun"> {
+    /** A caller-owned, existing probe session. Verification never creates sessions. */
+    readonly session?: string;
+    readonly agent?: string;
+}
+interface Rule {
+    action: string;
+    resource: string;
+    effect: "allow" | "deny" | "ask";
+}
+export interface ClientIsolationPlan {
+    readonly client: "opencode";
+    readonly project: string;
+    readonly set: string | null;
+    readonly members: readonly string[];
+    readonly config: string;
+    readonly receipt: string;
+    readonly changes: readonly {
+        path: string;
+        action: "create" | "update" | "remove";
+    }[];
+    readonly recovery: boolean;
+    readonly overrides: readonly {
+        path: string;
+        rule: number;
+    }[];
+}
+export interface ClientIsolationResult extends ClientIsolationPlan {
+    readonly dryRun: boolean;
+    readonly applied: boolean;
+    readonly runtimeVerified: false;
+}
+export interface ClientVerification {
+    readonly client: "opencode";
+    readonly project: string;
+    readonly set: string;
+    readonly session: string;
+    readonly agent: string;
+    readonly evidence: "opencode-v2-permission-evaluator";
+    readonly registryCount: number;
+    readonly checked: readonly {
+        id: string;
+        expected: Rule["effect"];
+        effect: Rule["effect"];
+        request: string;
+    }[];
+    readonly advertised: readonly string[];
+}
+/** Native V2 API envelope; a transport seam for fixtures, not an alternate evaluator. */
+export type OpenCodeRequest = (method: "get" | "post", path: string, body?: Readonly<Record<string, unknown>>) => Promise<unknown>;
+export declare class ClientIsolationCommand {
+    readonly options: ClientIsolationOptions;
+    readonly remove: boolean;
+    constructor(options: ClientIsolationOptions, remove?: boolean);
+    plan(): Promise<ClientIsolationPlan>;
+    execute(): Promise<ResultEnvelope<ClientIsolationResult | null>>;
+}
+export declare function isolateClient(options: ClientIsolationOptions): Promise<ResultEnvelope<ClientIsolationResult | null>>;
+/** Removes only receipt-owned rules; works after the project set has been unset. */
+export declare function unisolateClient(options: ClientIsolationOptions): Promise<ResultEnvelope<ClientIsolationResult | null>>;
+/** Checks the actual permission service, including agent and session overrides, without inference. */
+export declare function verifyClientIsolation(options: ClientVerifyOptions, request?: OpenCodeRequest): Promise<ResultEnvelope<ClientVerification | null>>;
+export {};

package/dist/core/composition-mutation.d.ts

@@ -8,6 +8,14 @@ interface LinkIdentity {
     readonly raw: string;
     readonly target: string;
 }
+export interface CompositionDocument {
+    readonly path: string;
+    readonly bytes: Buffer;
+    readonly before?: {
+        bytes: Buffer;
+        info: Stats;
+    };
+}
 export interface CompositionPlan {
     readonly registry: RegistrySelection;
     readonly composition: CompositionDetails;
@@ -15,14 +23,8 @@ export interface CompositionPlan {
     readonly changes: CompositionChange[];
     readonly directories: Map<string, Stats>;
     readonly links: Map<string, LinkIdentity>;
-    manifest?: {
-        path: string;
-        bytes: Buffer;
-        before?: {
-            bytes: Buffer;
-            info: Stats;
-        };
-    };
+    manifest?: CompositionDocument;
+    origin?: CompositionDocument;
 }
 export declare function compositionError<T>(command: string, error: unknown): ResultEnvelope<T | null>;
 export declare function conflict(path: string, message?: string): never;

package/dist/core/composition-types.d.ts

@@ -17,7 +17,7 @@ export interface CompositionDetails {
     readonly description?: string;
 }
 export interface CompositionChange {
-    readonly action: "create-directory" | "create-link" | "remove-link" | "write-manifest";
+    readonly action: "create-directory" | "create-link" | "remove-link" | "write-manifest" | "write-origin";
     readonly path: string;
     readonly target?: string;
 }

package/dist/core/derivation.d.ts

@@ -0,0 +1,59 @@
+import type { CompositionChange, CompositionMutationData, CompositionOptions } from "./composition-types.js";
+import { type ResultEnvelope } from "./result.js";
+import type { RegistrySelection, ScopeName } from "./selection.js";
+import { type DerivedSetDeclaration, type SetOrigin } from "./set-origin.js";
+export interface DerivationOwner {
+    readonly scope: ScopeName;
+    readonly root: string;
+}
+export interface DerivationInputs {
+    readonly base: string | null;
+    readonly packs: readonly string[];
+    readonly skills: readonly string[];
+    readonly removed: readonly string[];
+}
+export interface DerivationPreview {
+    readonly registry: RegistrySelection;
+    readonly owner: DerivationOwner;
+    readonly name: string;
+    readonly path: string;
+    readonly inputs: DerivationInputs;
+    readonly members: readonly {
+        readonly name: string;
+        readonly path: string;
+    }[];
+    readonly creates: boolean;
+    readonly changes: readonly CompositionChange[];
+}
+/** Membership a derived set must materialize: base ∪ packs ∪ skills − removed. */
+export declare function desiredDerivedMembers(registry: string, inputs: DerivationInputs, ancestors?: ReadonlySet<string>): Promise<Map<string, string>>;
+/** Validate the complete derived projection, not just the links that survived. */
+export declare function verifyDerivedMembers(registry: string, inventory: {
+    readonly path: string;
+    readonly names: readonly string[];
+}, derived: DerivedSetDeclaration, ancestors?: ReadonlySet<string>): Promise<void>;
+/** Read the current derivation state of a set, if it is a derived set at all. */
+export declare function derivedState(registry: string, name: string): Promise<{
+    path: string;
+    origin: SetOrigin & {
+        derived: DerivedSetDeclaration;
+    };
+    members: string[];
+} | undefined>;
+/** The name of the derived set this scope owns for the given base. */
+export declare function ownedDerivedName(base: string | null, ownerRoot: string): string;
+/** Read-only derivation preview for command planning and dry runs. */
+export declare function planDerivedSet(options: CompositionOptions & {
+    owner: DerivationOwner;
+    inputs: DerivationInputs;
+}): Promise<DerivationPreview>;
+/** Materialize (or update) the scope-owned derived set. Registry-only write. */
+export declare function materializeDerivedSet(options: CompositionOptions & {
+    owner: DerivationOwner;
+    inputs: DerivationInputs;
+}): Promise<ResultEnvelope<CompositionMutationData | null>>;
+/** Remove only an owned derived set, serialized with every composition writer. */
+export declare function retireDerivedSet(options: CompositionOptions, owner: DerivationOwner, name: string): Promise<ResultEnvelope<{
+    retired: string | null;
+    removed: readonly string[];
+} | null>>;

package/dist/core/diagnostics-types.d.ts

@@ -9,7 +9,7 @@ export interface PathObservation {
     readonly rawTarget: string | null;
     readonly target: string | null;
     readonly reachable: boolean;
-    readonly ownership: "owned" | "foreign" | "changed" | "pack" | "none";
+    readonly ownership: "owned" | "foreign" | "changed" | "set" | "none";
 }
 export interface SkillObservation extends PathObservation {
     readonly name: string;
@@ -30,7 +30,7 @@ export interface StatusScope {
     readonly scope: ScopeName;
     readonly root: string;
     readonly manifestPath: string;
-    readonly mode: "composed" | "pack" | null;
+    readonly mode: "composed" | "set" | null;
     readonly desired: readonly string[] | null;
     readonly actual: {
         readonly root: PathObservation;
@@ -41,7 +41,7 @@ export interface StatusScope {
         readonly actual: number;
         readonly owned: number;
         readonly foreign: number;
-        readonly pack: number;
+        readonly set: number;
         readonly missing: number | null;
     };
     readonly aliases: readonly AliasObservation[];

package/dist/core/import-sources.d.ts

@@ -0,0 +1,131 @@
+import type { CompositionOptions } from "./composition-types.js";
+import { type Diagnostic } from "./result.js";
+export interface SourceEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly disposition: "mapped" | "unmapped" | "divergent" | "broken" | "foreign";
+    readonly canonical?: string;
+    /** Real directory an explicit import would copy from (links resolve first). */
+    readonly importPath?: string;
+    readonly reason?: string;
+}
+export interface SourceProvenance {
+    readonly type: "path" | "git";
+    readonly label: string;
+    readonly commit?: string;
+}
+export interface SourceInventory {
+    readonly label: string;
+    readonly kind: "path" | "git";
+    readonly root: string | undefined;
+    readonly entries: readonly SourceEntry[];
+    readonly provenance: SourceProvenance;
+    readonly temporary: string | undefined;
+    readonly findings: readonly Diagnostic[];
+}
+export interface SourceOptions {
+    readonly cwd?: string;
+    readonly home?: string;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}
+/** One source skill that has no canonical definition yet. */
+export interface PendingImport {
+    readonly name: string;
+    readonly path: string;
+    /** Stable provenance label: sanitized URL (plus commit for Git), never a clone temp path. */
+    readonly label: string;
+}
+export interface MembershipOptions {
+    /** Collect unmapped entries for explicit import instead of refusing on them. */
+    readonly importMissing?: boolean;
+}
+export interface SourceMembership {
+    readonly names: string[];
+    readonly findings: Diagnostic[];
+    readonly imports: PendingImport[];
+}
+/** Options shared by source-backed set/pack creation. */
+export interface SourceCreationOptions extends CompositionOptions {
+    readonly fromRoot?: string;
+    readonly from?: readonly string[];
+    readonly import?: boolean;
+}
+/** The membership slice of {@link PlannedSources} that composition planning consumes. */
+export interface SourceMembershipPlan {
+    readonly members: readonly string[];
+    readonly pending: ReadonlyMap<string, string>;
+    readonly provenance: Record<string, unknown> | undefined;
+}
+/**
+ * Remove URL credentials anywhere they appear — labels, provenance, findings,
+ * and Git transport errors all pass through here — so a token or password
+ * embedded for transport is never echoed back.
+ */
+export declare function sanitizeSourceLabel(source: string): string;
+export declare function releaseInventory(inventory: SourceInventory): Promise<void>;
+export declare function inventorySkillRoot(registry: string, path: string, options?: SourceOptions): Promise<SourceInventory>;
+/**
+ * Inventory one explicitly requested source: an existing local path is read in
+ * place; a Git remote is acquired (clone --depth 1) because it was explicitly
+ * requested, with its commit pinned into provenance. Nothing is executed from
+ * the acquired tree and nothing is imported implicitly.
+ */
+export declare function inventorySource(registry: string, source: string, options?: SourceOptions, pinned?: SourceProvenance): Promise<SourceInventory>;
+/**
+ * Merge inventories into canonical member names. Mapped entries become
+ * members; divergent and broken entries are errors; foreign entries are
+ * preserved and reported. Unmapped entries are errors unless importMissing
+ * collected them for explicit import — a requested entry is never skipped
+ * silently.
+ */
+export declare function membersFromInventories(registry: string, inventories: readonly SourceInventory[], options?: MembershipOptions): Promise<SourceMembership>;
+/**
+ * Acquire every declared source. When a later source fails, every inventory
+ * acquired so far — including its ephemeral clone — is released before the
+ * error propagates, so a failed acquisition never strands a temp tree.
+ */
+export declare function acquireInventories(registryRoot: string, options: SourceCreationOptions): Promise<SourceInventory[]>;
+/** Sources fully planned: membership merged, every import validated write-free. */
+export interface PlannedSources {
+    readonly inventories: readonly SourceInventory[];
+    readonly names: readonly string[];
+    /** Canonical destinations the planned imports will occupy (dry-run results). */
+    readonly pending: ReadonlyMap<string, string>;
+    readonly imports: readonly PendingImport[];
+    readonly findings: readonly Diagnostic[];
+}
+/**
+ * Acquire all sources and plan membership without a single write: every
+ * would-be import is validated through the standing `skill import` machinery
+ * in dry-run first, so an invalid name or unreadable source refuses before
+ * any catalog byte moves. Import failures surface as error findings.
+ */
+export declare function planSourceMembers(registryRoot: string, options: SourceCreationOptions): Promise<PlannedSources>;
+/** An import that actually landed in the catalog. */
+export interface ExecutedImport {
+    readonly name: string;
+    readonly path: string;
+}
+/** Result of executing planned imports for real. */
+export interface ImportExecution {
+    readonly executed: readonly ExecutedImport[];
+    readonly findings: readonly Diagnostic[];
+}
+/**
+ * Execute planned imports for real, reusing the standing `skill import`
+ * machinery. A failing import never invents a rollback or deletes the
+ * definitions earlier imports already wrote — they are standalone
+ * receipt-bearing units — but their survival is disclosed truthfully so the
+ * refusal is never a silent partial state.
+ */
+export declare function executeImports(imports: readonly PendingImport[], options: SourceCreationOptions): Promise<ImportExecution>;
+export declare function provenanceFrom(inventories: readonly SourceInventory[], imported?: readonly string[]): Promise<Record<string, unknown> | undefined>;
+/**
+ * Validate member names with the shared manifest authority and resolve each
+ * to its canonical target. `pending` carries dry-run import destinations for
+ * names whose canonical does not exist yet; every other name must resolve for
+ * real or the operation refuses.
+ */
+export declare function resolveMemberTargets(registry: string, names: readonly string[], label: string, pending?: ReadonlyMap<string, string>): Promise<Map<string, string>>;

package/dist/core/normalization.d.ts

@@ -0,0 +1,15 @@
+import { type ResultEnvelope } from "./result.js";
+import type { SelectionOptions, SelectionResult } from "./selection-command-types.js";
+export interface NormalizeOptions extends SelectionOptions {
+    /** Apply the planned repair. Without it, normalize is a write-free preview. */
+    readonly apply?: boolean;
+    /** Explicit base for a legacy multi-set selection; never guessed from array order. */
+    readonly baseSet?: string;
+}
+/**
+ * Normalize one scope's selection declaration to the corrected set/pack
+ * contract: inventory legacy or conflicted state, fold it into deterministic
+ * exact-membership references, and preview (default) or apply the repair
+ * through the shared selection transaction.
+ */
+export declare function normalizeScope(options?: NormalizeOptions): Promise<ResultEnvelope<SelectionResult | null>>;

package/dist/core/packs.d.ts

@@ -1,8 +1,16 @@
 import type { CompositionMutationData, CompositionOptions, PackListData, PackShowData } from "./composition-types.js";
 import { type ResultEnvelope } from "./result.js";
+export interface CreatePackOptions extends CompositionOptions {
+    /** Existing local skill root whose entries become member references. */
+    readonly fromRoot?: string;
+    /** Repeatable explicit sources: existing paths or Git remotes. */
+    readonly from?: readonly string[];
+    /** Import source skills that have no canonical definition instead of refusing. */
+    readonly import?: boolean;
+}
 export declare function listPacks(options?: CompositionOptions): Promise<ResultEnvelope<PackListData | null>>;
 export declare function showPack(ref: string, options?: CompositionOptions): Promise<ResultEnvelope<PackShowData | null>>;
 export declare function verifyPack(ref: string, options?: CompositionOptions): Promise<ResultEnvelope<PackShowData | null>>;
-export declare function createPack(name: string, version: string, options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;
+export declare function createPack(name: string, version: string, options?: CreatePackOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;
 export declare function addPackSkills(ref: string, names: readonly string[], options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;
 export declare function removePackSkills(ref: string, names: readonly string[], options?: CompositionOptions): Promise<ResultEnvelope<CompositionMutationData | null>>;

package/dist/core/profile-policy.d.ts

@@ -1,4 +1,6 @@
 import type { ProfileLocalEntry, ProfileLocation, ProfileOptions } from "./profile-types.js";
 export declare function strictProfile(profile: ProfileLocation, options: ProfileOptions): Promise<boolean>;
+/** Persist a profile's selection boundary independently of the caller's HOME. */
+export declare function profileInheritsGlobal(profile: ProfileLocation): Promise<boolean>;
 export declare function assertStrictProfile(profile: ProfileLocation, options: ProfileOptions, local: readonly ProfileLocalEntry[]): Promise<boolean>;
 export declare function publishStrictPolicy(profile: ProfileLocation): Promise<void>;

package/dist/core/reconciliation-types.d.ts

@@ -17,7 +17,7 @@ export interface SyncScopePlan {
     readonly scope: ScopeName;
     readonly root: string;
     readonly activationRoot: string;
-    readonly mode: "composed" | "pack";
+    readonly mode: "composed" | "set";
     readonly skills: readonly {
         readonly name: string;
         readonly path: string;

package/dist/core/reconciliation.d.ts

@@ -1,8 +1,9 @@
 import { type ReceiptOptions, type ReceiptSnapshot } from "./activation-state.js";
 import type { ActivationData, ActivationJournal, EntryIdentity, OwnedNode, SourceRevision } from "./activation-types.js";
+import { type DerivationPreview } from "./derivation.js";
 import type { SyncChange, SyncOptions, SyncPlan, SyncResult, SyncScopePlan } from "./reconciliation-types.js";
 import { type Diagnostic, type ResultEnvelope } from "./result.js";
-import type { Resolution, ResolvedScope } from "./selection.js";
+import type { Resolution, ResolvedScope, SkillsManifest } from "./selection.js";
 interface Operation {
     readonly path: string;
     readonly previous?: OwnedNode;
@@ -38,6 +39,13 @@ export interface PreparedSync {
 }
 /** Internal shared revision evidence for scope and profile receipts. */
 export declare function sourceRevision(kind: SourceRevision["kind"], path: string): Promise<SourceRevision>;
+/**
+ * Plan-only boundary for a set not yet materialized. Reuses every destination,
+ * receipt, recovery and alias guard; only the on-disk set check is replaced by
+ * validated derivation inputs. No executable ScopeWork escapes this function.
+ * Activation still re-resolves and verifies the actual set after materializing.
+ */
+export declare function preflightDerivedActivation(options: SyncOptions, manifest: SkillsManifest, preview: DerivationPreview): Promise<SyncScopePlan>;
 /** Read-only internal preparation; callers must not retain it across lock acquisitions. */
 export declare function prepareSyncUnlocked(options?: SyncOptions, proposed?: ReadonlyMap<string, unknown>, expected?: ReadonlyMap<string, unknown>): Promise<PreparedSync>;
 /** Internal C06 boundary: caller holds the activation lock; this function re-resolves intent itself. */

package/dist/core/retired-mise.d.ts

@@ -0,0 +1,36 @@
+import { type LockOptions } from "./lock.js";
+import { type ResultEnvelope } from "./result.js";
+export interface RetireMiseOptions extends LockOptions {
+    readonly project?: string;
+    readonly global?: boolean;
+    readonly file?: string;
+    readonly cwd?: string;
+    readonly apply?: boolean;
+    readonly dryRun?: boolean;
+}
+export interface RetiredMiseChange {
+    readonly path: string;
+    readonly tasks: readonly string[];
+    readonly references: number;
+}
+export interface RetiredMiseResult {
+    readonly dryRun: boolean;
+    readonly changes: readonly RetiredMiseChange[];
+    readonly applied: readonly string[];
+}
+/** Remove only proven skill-operation tables and their call edges. Never execute mise. */
+export declare function retireMiseText(text: string, path?: string): {
+    text: string;
+    tasks: string[];
+    references: number;
+};
+/** A first-class remediation command: read-only plan, guarded apply, then convergence check. */
+export declare class RetireMiseSkillTasksCommand {
+    readonly options: RetireMiseOptions;
+    constructor(options?: RetireMiseOptions);
+    private snapshots;
+    plan(): Promise<readonly RetiredMiseChange[]>;
+    verify(): Promise<boolean>;
+    execute(): Promise<ResultEnvelope<RetiredMiseResult | null>>;
+}
+export declare function retireMiseSkillTasks(options?: RetireMiseOptions): Promise<ResultEnvelope<RetiredMiseResult | null>>;

package/dist/core/root-cutover.d.ts

@@ -0,0 +1,52 @@
+import { type LockOptions } from "./lock.js";
+import { type MigrationNode } from "./migration-activation-state.js";
+import { type ResultEnvelope } from "./result.js";
+import type { RegistryOptions } from "./selection.js";
+export interface RootAdoptOptions extends RegistryOptions, LockOptions {
+    readonly project?: string;
+    /** Explicit OLD=NEW canonical identities; never inferred for broken or foreign entries. */
+    readonly map?: readonly string[];
+    /** Paired with replacePrefix: explicit pinned replacement authority, never inferred. */
+    readonly replacePack?: string;
+    readonly replacePrefix?: string;
+    readonly apply?: boolean;
+    readonly dryRun?: boolean;
+    readonly signal?: {
+        readonly aborted: boolean;
+    };
+}
+export interface RootAdoptEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: MigrationNode["identity"]["kind"] | "absent";
+    readonly raw?: string;
+    readonly canonical?: string;
+    readonly target?: string;
+    readonly source?: string;
+    /** Original resolution, absent for broken links, new pack members, or refused entries. */
+    readonly resolved?: string;
+    readonly action: "adopt" | "map" | "replace" | "retire" | "add" | "refuse";
+    readonly reason?: string;
+}
+export interface RootReplacementPolicy {
+    readonly pack: string;
+    readonly prefix: string;
+}
+export interface RootAdoptResult {
+    readonly project: string;
+    readonly root: string;
+    readonly dryRun: boolean;
+    readonly inventory: readonly RootAdoptEntry[];
+    readonly changes: readonly string[];
+    readonly applied: boolean;
+    readonly recovery: boolean;
+    /** Durable authored-content archive location, including when a completed archive is missing. */
+    readonly quarantine: string | null;
+    readonly archiveStatus: "none" | "planned" | "pending" | "verified" | "missing";
+    readonly receipt: string;
+    readonly journal: string;
+    readonly preservedStages: readonly string[];
+    readonly replacement: RootReplacementPolicy | null;
+}
+/** Project-only adoption. No selection resolver, manifest writer, alias writer, or registry migration runs. */
+export declare function adoptRoot(options?: RootAdoptOptions): Promise<ResultEnvelope<RootAdoptResult | null>>;

package/dist/core/selection-command-types.d.ts

@@ -6,7 +6,7 @@ export interface SelectionOptions extends Omit<SyncOptions, "scope" | "exitCode"
 }
 export interface SelectionChange {
     readonly scope: ScopeName;
-    readonly action: "write-manifest" | SyncChange["action"];
+    readonly action: "write-manifest" | "derive-set" | "retire-set" | SyncChange["action"];
     readonly path: string;
     readonly target?: string;
 }

package/dist/core/selection-commands.d.ts

@@ -1,6 +1,39 @@
 import { type ResultEnvelope } from "./result.js";
+import type { ScopeName } from "./selection.js";
 import type { SelectionKind, SelectionOptions, SelectionResult } from "./selection-command-types.js";
+interface Target {
+    readonly scope: ScopeName;
+    readonly root: string;
+    readonly home: string;
+}
+type Edit = {
+    readonly operation: "init";
+} | {
+    readonly operation: "inherit";
+    readonly enabled: boolean;
+} | {
+    readonly operation: "enable" | "disable";
+    readonly kind: SelectionKind;
+    readonly reference: string;
+} | {
+    readonly operation: "normalize";
+};
+/** An externally computed candidate with the exact raw it was inventoried from. */
+export interface SelectionOverride {
+    readonly expected: Readonly<Record<string, unknown>>;
+    readonly candidate: Readonly<Record<string, unknown>>;
+}
 export declare function initScope(options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
 export declare function enableSelection(kind: SelectionKind, reference: string, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
 export declare function disableSelection(kind: SelectionKind, reference: string, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
 export declare function setInheritance(enabled: boolean, options?: SelectionOptions): Promise<ResultEnvelope<SelectionResult | null>>;
+/** Scope selection shared by the selection commands and normalization. */
+export declare function selectScopeTarget(options: SelectionOptions, edit: Edit): Promise<Target>;
+export type { Target as ScopeTarget };
+/**
+ * Run one prepared edit against the shared manifest/activation transaction.
+ * Normalization passes an explicit candidate (inventoried from an exact raw
+ * declaration, re-verified under the lock) plus tolerant legacy reads.
+ */
+export declare function runSelectionEdit(edit: Edit, options: SelectionOptions, override?: SelectionOverride, tolerant?: boolean): Promise<ResultEnvelope<SelectionResult | null>>;
+export type { Edit as SelectionEdit };

package/dist/core/selection-manifest.d.ts

@@ -1,4 +1,5 @@
 import { SkillexError } from "./error.js";
+import { type Diagnostic } from "./result.js";
 import type { SkillsManifest } from "./selection.js";
 export interface SelectionManifestSnapshot {
     readonly root: string;
@@ -6,6 +7,11 @@ export interface SelectionManifestSnapshot {
     readonly exists: boolean;
     readonly raw: Readonly<Record<string, unknown>> | null;
     readonly manifest: SkillsManifest | null;
+    /**
+     * Parse findings a tolerant read recovered from a declaration that ordinary
+     * sync refuses. Present only when `manifest` is null while `raw` was read.
+     */
+    readonly parseFindings?: readonly Diagnostic[];
 }
 /** The declaration may already be saved even when later durability checks fail. */
 export declare class SelectionManifestWriteError extends SkillexError {
@@ -13,6 +19,8 @@ export declare class SelectionManifestWriteError extends SkillexError {
     constructor(error: SkillexError, published: boolean);
 }
 /** Inspect one source declaration. Missing .agents/skills.json never creates anything. */
-export declare function readSelectionManifest(root: string): Promise<SelectionManifestSnapshot>;
+export declare function readSelectionManifest(root: string, options?: {
+    readonly tolerant?: boolean;
+}): Promise<SelectionManifestSnapshot>;
 /** Validate and atomically publish while the caller holds the shared activation lock. */
 export declare function writeSelectionManifest(previous: SelectionManifestSnapshot, raw: Readonly<Record<string, unknown>>): Promise<SelectionManifestSnapshot>;