@ai-plugin-marketplace/core 0.2.0 → 0.4.0

package/dist/pipeline/operations.d.ts

@@ -9,7 +9,7 @@
  *
  * @see docs/specs/architecture.md §8.1
  */
-import type { BuildOptions, BuildResult, InitOptions, MigrateOptions, MigrateResult, ScaffoldOptions, SupportReport, TargetId, ValidateOptions, ValidationResult } from './types.js';
+import type { BuildOptions, BuildResult, InitOptions, MigrateOptions, MigrateResult, RefreshOptions, RefreshOutcome, ScaffoldOptions, SupportReport, TargetId, ValidateOptions, ValidationResult } from './types.js';
 /**
  * Build a single plugin or every plugin under a repo root. `path` may be a plugin directory
  * (contains `aipm.config.ts`) or a repo root (contains `plugins/`); the orchestrator detects
@@ -34,6 +34,16 @@ export declare function validate(targetPath: string, opts?: ValidateOptions): Pr
  * @public
  */
 export declare function init(targetDir: string, opts?: InitOptions): Promise<void>;
+/**
+ * Refresh the toolkit-owned scaffold files (CI workflow, `.gitignore`) of an existing marketplace
+ * repo at `targetDir` to match the installed tooling — the upgrade path after
+ * `pnpm up @ai-plugin-marketplace/*`. Guarded by the `.aipm/scaffold.json` content-hash sidecar:
+ * user-modified files are reported as conflicts and left untouched unless `opts.force` is set.
+ * Returns one outcome per managed file; never rejects on conflict.
+ *
+ * @public
+ */
+export declare function refreshScaffold(targetDir: string, opts?: RefreshOptions): Promise<RefreshOutcome[]>;
 /**
  * Scaffold a new plugin under the cwd's configured plugins root (`<cwd>/plugins/<name>` by
  * default, or the relocated `pluginsRoot` from an `aipm.repo.ts`). The plugins directory is

package/dist/pipeline/operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/pipeline/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,QAAQ,EACR,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAE9F;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,SAAS,QAAQ,EAAE,CAEjD"}
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/pipeline/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAWH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,QAAQ,EACR,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAE9F;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,cAAc,EAAE,CAAC,CAK3B;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtF;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAMrF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,SAAS,QAAQ,EAAE,CAEjD"}

package/dist/pipeline/operations.js

@@ -13,6 +13,7 @@ import * as path from 'node:path';
 import { runBuild } from './build.js';
 import { runInit } from './init.js';
 import { loadRepoConfig } from './load-config.js';
+import { runRefreshScaffold } from './scaffold-refresh.js';
 import { runScaffold, runAddTarget, runCheckSupport } from './scaffold.js';
 import { TARGET_IDS } from './types.js';
 import { runValidate } from './validate.js';
@@ -50,6 +51,21 @@ export function validate(targetPath, opts) {
 export function init(targetDir, opts) {
     return runInit(targetDir, opts);
 }
+/**
+ * Refresh the toolkit-owned scaffold files (CI workflow, `.gitignore`) of an existing marketplace
+ * repo at `targetDir` to match the installed tooling — the upgrade path after
+ * `pnpm up @ai-plugin-marketplace/*`. Guarded by the `.aipm/scaffold.json` content-hash sidecar:
+ * user-modified files are reported as conflicts and left untouched unless `opts.force` is set.
+ * Returns one outcome per managed file; never rejects on conflict.
+ *
+ * @public
+ */
+export function refreshScaffold(targetDir, opts) {
+    // Defer into the microtask queue so a synchronous failure in the orchestrator (e.g. an I/O error)
+    // surfaces as a rejected promise — matching `refreshScaffold(...).catch(...)` expectations —
+    // rather than throwing from this call before the promise exists.
+    return Promise.resolve().then(() => runRefreshScaffold(targetDir, opts));
+}
 /**
  * Scaffold a new plugin under the cwd's configured plugins root (`<cwd>/plugins/<name>` by
  * default, or the relocated `pluginsRoot` from an `aipm.repo.ts`). The plugins directory is

package/dist/pipeline/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/pipeline/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAc5C,sGAAsG;AACtG,SAAS,IAAI;IACX,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,UAAkB,EAAE,IAAmB;IAC3D,OAAO,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,UAAkB,EAAE,IAAsB;IACjE,OAAO,WAAW,CAAC,UAAU,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,SAAiB,EAAE,IAAkB;IACxD,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAwB,EAAE;IACrE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,KAAsB;IAC3D,OAAO,OAAO,CAAC,OAAO,CAAC;QACrB,MAAM,EAAE,sBAAsB;QAC9B,iBAAiB,EAAE,CAAC;QACpB,YAAY,EAAE,EAAE;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,MAAgB;IAC3D,OAAO,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/pipeline/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAgB5C,sGAAsG;AACtG,SAAS,IAAI;IACX,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,UAAkB,EAAE,IAAmB;IAC3D,OAAO,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,UAAkB,EAAE,IAAsB;IACjE,OAAO,WAAW,CAAC,UAAU,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAC,SAAiB,EAAE,IAAkB;IACxD,OAAO,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,IAAqB;IAErB,kGAAkG;IAClG,6FAA6F;IAC7F,iEAAiE;IACjE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAwB,EAAE;IACrE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,KAAsB;IAC3D,OAAO,OAAO,CAAC,OAAO,CAAC;QACrB,MAAM,EAAE,sBAAsB;QAC9B,iBAAiB,EAAE,CAAC;QACpB,YAAY,EAAE,EAAE;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,MAAgB;IAC3D,OAAO,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/pipeline/scaffold-refresh.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `aipm init --refresh` — keep a marketplace repo's **toolkit-owned scaffold files** (the CI
+ * workflow and `.gitignore`) in sync with the installed tooling, and serve as the upgrade path for
+ * any marketplace repo after `pnpm up @ai-plugin-marketplace/*`.
+ *
+ * Safety rests on a content-hash sidecar at `.aipm/scaffold.json` (mirroring the root-emission
+ * sidecar `.aipm/generated-root.json`): it records a hash of the exact content the toolkit last
+ * wrote each managed file. Refresh updates a file only when it is still pristine (matches the
+ * recorded hash) or missing; a file the user has edited surfaces as a reported conflict and is left
+ * untouched unless `--force` is given. A repo with no sidecar entry bootstraps: an already-in-sync
+ * file is adopted silently, a diverged one is a conflict to review.
+ *
+ * The managed set is deliberately narrow — only the pure tooling-recipe files (see
+ * {@link buildManagedScaffoldFiles}). `package.json` (deps are `pnpm up`'s job), `aipm.workspace.ts`
+ * (repo identity), `README.md` (authored), plugins, and `aipm build` output are never touched.
+ *
+ * @see docs/specs/scaffold-refresh-and-upgrade.md
+ */
+import type { RefreshOptions, RefreshOutcome } from './types.js';
+/** A recorded `{ path, hash }` pair: the hash of the content the toolkit last wrote at `path`. */
+interface SidecarEntry {
+    path: string;
+    hash: string;
+}
+/** Content hash recorded in the sidecar. `sha256-`-prefixed hex over the UTF-8 bytes. */
+export declare function hashScaffoldContent(content: string): string;
+/**
+ * Serialize a sidecar payload: `{ version, files }` with `files` sorted by path for determinism,
+ * 2-space JSON + trailing newline (matching the repo's other generated JSON).
+ */
+export declare function serializeScaffoldSidecar(entries: readonly SidecarEntry[]): string;
+/** Inputs to the pure per-file refresh decision. */
+export interface ManagedFileDecisionInput {
+    /** Canonical content the toolkit would render for this file. */
+    render: string;
+    /** Current on-disk content, or `null` when the file is missing. */
+    current: string | null;
+    /** Hash recorded in the sidecar for this file, or `null` when untracked. */
+    recordedHash: string | null;
+    /** Whether `--force` was given. */
+    force: boolean;
+}
+/** Result of the pure per-file refresh decision. */
+export interface ManagedFileDecision {
+    status: RefreshOutcome['status'];
+    /** Whether to write `render` to disk. */
+    write: boolean;
+    /** Hash to record in the new sidecar, or `null` to preserve the prior entry (or stay untracked). */
+    recordHash: string | null;
+}
+/**
+ * Decide what to do with one managed scaffold file. Pure — all filesystem state is passed in — so
+ * the decision table is unit-testable in isolation.
+ *
+ * | On-disk state                                   | Result        |
+ * |-------------------------------------------------|---------------|
+ * | missing                                         | `recreated`   |
+ * | matches the current render                      | `unchanged`   |
+ * | differs from render, matches recorded hash      | `updated`     |
+ * | differs from render & recorded (or untracked)   | `conflict` *  |
+ * | …same, with `force`                             | `overwritten` |
+ *
+ * \* `unchanged` also adopts an untracked-but-in-sync file by recording its hash.
+ */
+export declare function decideManagedFile(input: ManagedFileDecisionInput): ManagedFileDecision;
+/**
+ * Seed `.aipm/scaffold.json` for a freshly scaffolded repo, recording the hash of every managed
+ * scaffold file as just written by `aipm init`. Called by {@link runInit} after the seed tree is
+ * written so the first `--refresh` has a baseline.
+ */
+export declare function writeScaffoldSidecar(repoRoot: string): void;
+/**
+ * Refresh the toolkit-owned scaffold files of an existing repo at `repoRoot`, re-rendering each
+ * from the installed tooling and updating it in place when safe (see {@link decideManagedFile}).
+ * Writes the updated `.aipm/scaffold.json` sidecar and returns one {@link RefreshOutcome} per
+ * managed file. Never throws on conflict — conflicts are reported, not failures.
+ */
+export declare function runRefreshScaffold(repoRoot: string, opts?: RefreshOptions): RefreshOutcome[];
+export {};
+//# sourceMappingURL=scaffold-refresh.d.ts.map

package/dist/pipeline/scaffold-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-refresh.d.ts","sourceRoot":"","sources":["../../src/pipeline/scaffold-refresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOjE,kGAAkG;AAClG,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAOD,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAGjF;AA+BD,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACjC,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,oGAAoG;IACpG,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,GAAG,mBAAmB,CAmBtF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,cAAc,EAAE,CAmChG"}

package/dist/pipeline/scaffold-refresh.js

@@ -0,0 +1,152 @@
+/**
+ * `aipm init --refresh` — keep a marketplace repo's **toolkit-owned scaffold files** (the CI
+ * workflow and `.gitignore`) in sync with the installed tooling, and serve as the upgrade path for
+ * any marketplace repo after `pnpm up @ai-plugin-marketplace/*`.
+ *
+ * Safety rests on a content-hash sidecar at `.aipm/scaffold.json` (mirroring the root-emission
+ * sidecar `.aipm/generated-root.json`): it records a hash of the exact content the toolkit last
+ * wrote each managed file. Refresh updates a file only when it is still pristine (matches the
+ * recorded hash) or missing; a file the user has edited surfaces as a reported conflict and is left
+ * untouched unless `--force` is given. A repo with no sidecar entry bootstraps: an already-in-sync
+ * file is adopted silently, a diverged one is a conflict to review.
+ *
+ * The managed set is deliberately narrow — only the pure tooling-recipe files (see
+ * {@link buildManagedScaffoldFiles}). `package.json` (deps are `pnpm up`'s job), `aipm.workspace.ts`
+ * (repo identity), `README.md` (authored), plugins, and `aipm build` output are never touched.
+ *
+ * @see docs/specs/scaffold-refresh-and-upgrade.md
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { buildManagedScaffoldFiles } from './init-template.js';
+/** Sidecar location relative to the repo root. */
+const SIDECAR_REL = ['.aipm', 'scaffold.json'];
+/** Schema version of the sidecar payload. */
+const SIDECAR_VERSION = 1;
+/** Absolute path of the scaffold sidecar under `repoRoot`. */
+function sidecarPath(repoRoot) {
+    return path.join(repoRoot, ...SIDECAR_REL);
+}
+/** Content hash recorded in the sidecar. `sha256-`-prefixed hex over the UTF-8 bytes. */
+export function hashScaffoldContent(content) {
+    return `sha256-${createHash('sha256').update(content, 'utf-8').digest('hex')}`;
+}
+/**
+ * Serialize a sidecar payload: `{ version, files }` with `files` sorted by path for determinism,
+ * 2-space JSON + trailing newline (matching the repo's other generated JSON).
+ */
+export function serializeScaffoldSidecar(entries) {
+    const files = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+    return `${JSON.stringify({ version: SIDECAR_VERSION, files }, null, 2)}\n`;
+}
+/** Read the prior sidecar into a `path → hash` map. Missing or malformed sidecar → empty map. */
+function readSidecar(repoRoot) {
+    const map = new Map();
+    const abs = sidecarPath(repoRoot);
+    if (!fs.existsSync(abs))
+        return map;
+    // Read errors (permissions, transient I/O) propagate — they are real operational problems, not a
+    // "malformed sidecar" we should silently swallow. Only a JSON parse failure is tolerated.
+    const raw = fs.readFileSync(abs, 'utf-8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // A malformed sidecar is treated as absent: every managed file becomes "untracked" and must
+        // either already match the current render (adopted) or be resolved via --force.
+        return map;
+    }
+    if (Array.isArray(parsed.files)) {
+        for (const rawEntry of parsed.files) {
+            const entry = rawEntry;
+            if (typeof entry.path === 'string' && typeof entry.hash === 'string') {
+                map.set(entry.path, entry.hash);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Decide what to do with one managed scaffold file. Pure — all filesystem state is passed in — so
+ * the decision table is unit-testable in isolation.
+ *
+ * | On-disk state                                   | Result        |
+ * |-------------------------------------------------|---------------|
+ * | missing                                         | `recreated`   |
+ * | matches the current render                      | `unchanged`   |
+ * | differs from render, matches recorded hash      | `updated`     |
+ * | differs from render & recorded (or untracked)   | `conflict` *  |
+ * | …same, with `force`                             | `overwritten` |
+ *
+ * \* `unchanged` also adopts an untracked-but-in-sync file by recording its hash.
+ */
+export function decideManagedFile(input) {
+    const { render, current, recordedHash, force } = input;
+    const renderHash = hashScaffoldContent(render);
+    if (current === null)
+        return { status: 'recreated', write: true, recordHash: renderHash };
+    const currentHash = hashScaffoldContent(current);
+    if (currentHash === renderHash)
+        return { status: 'unchanged', write: false, recordHash: renderHash };
+    // Content differs from the current render.
+    if (recordedHash !== null && currentHash === recordedHash) {
+        // Pristine: the file is exactly what the toolkit last wrote, so it is safe to upgrade.
+        return { status: 'updated', write: true, recordHash: renderHash };
+    }
+    // Diverged from the recorded hash (user-edited) or untracked and not in sync.
+    if (force)
+        return { status: 'overwritten', write: true, recordHash: renderHash };
+    return { status: 'conflict', write: false, recordHash: null };
+}
+/**
+ * Seed `.aipm/scaffold.json` for a freshly scaffolded repo, recording the hash of every managed
+ * scaffold file as just written by `aipm init`. Called by {@link runInit} after the seed tree is
+ * written so the first `--refresh` has a baseline.
+ */
+export function writeScaffoldSidecar(repoRoot) {
+    const entries = buildManagedScaffoldFiles().map((file) => ({
+        path: file.path,
+        hash: hashScaffoldContent(file.content),
+    }));
+    const abs = sidecarPath(repoRoot);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, serializeScaffoldSidecar(entries), 'utf-8');
+}
+/**
+ * Refresh the toolkit-owned scaffold files of an existing repo at `repoRoot`, re-rendering each
+ * from the installed tooling and updating it in place when safe (see {@link decideManagedFile}).
+ * Writes the updated `.aipm/scaffold.json` sidecar and returns one {@link RefreshOutcome} per
+ * managed file. Never throws on conflict — conflicts are reported, not failures.
+ */
+export function runRefreshScaffold(repoRoot, opts = {}) {
+    const force = opts.force ?? false;
+    const resolved = path.resolve(repoRoot);
+    const recorded = readSidecar(resolved);
+    const outcomes = [];
+    const newEntries = [];
+    for (const file of buildManagedScaffoldFiles()) {
+        const abs = path.join(resolved, file.path);
+        const current = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf-8') : null;
+        const recordedHash = recorded.get(file.path) ?? null;
+        const decision = decideManagedFile({ render: file.content, current, recordedHash, force });
+        if (decision.write) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, file.content, 'utf-8');
+        }
+        if (decision.recordHash !== null) {
+            newEntries.push({ path: file.path, hash: decision.recordHash });
+        }
+        else if (recordedHash !== null) {
+            // Conflict left untouched: preserve the prior recorded hash so it stays tracked.
+            newEntries.push({ path: file.path, hash: recordedHash });
+        }
+        outcomes.push({ path: file.path, status: decision.status });
+    }
+    const sidecarAbs = sidecarPath(resolved);
+    fs.mkdirSync(path.dirname(sidecarAbs), { recursive: true });
+    fs.writeFileSync(sidecarAbs, serializeScaffoldSidecar(newEntries), 'utf-8');
+    return outcomes;
+}
+//# sourceMappingURL=scaffold-refresh.js.map

package/dist/pipeline/scaffold-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-refresh.js","sourceRoot":"","sources":["../../src/pipeline/scaffold-refresh.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/types.d.ts

@@ -99,9 +99,15 @@ export interface ValidationResult {
  * host software / the author). Generation refuses to overwrite it rather than clobber repo-root
  * state.
  *
+ * `default-marketplace-name` — the repo's effective marketplace `name` (or `owner.name`) is still
+ * a template placeholder (e.g. `ai-plugin-marketplace`, `my-ai-plugins`, `Your Name`). Two
+ * marketplaces registered under the same name collide on install — the later one shadows/strands
+ * the earlier one's plugins — so a placeholder must be renamed to a unique value. Always SOFT: a
+ * warning, never a build failure.
+ *
  * @public
  */
-export type FindingCode = 'envelope-invalid' | 'repo-config-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness' | 'single-artifact-host' | 'root-artifact-collision';
+export type FindingCode = 'envelope-invalid' | 'repo-config-invalid' | 'envelope-adherence' | 'schema-invalid' | 'name-consistency' | 'mcp-key-sync' | 'marketplace-registration' | 'freshness' | 'single-artifact-host' | 'root-artifact-collision' | 'default-marketplace-name';
 /**
  * A single validation finding.
  *
@@ -139,6 +145,56 @@ export interface InitOptions {
      * directory.
      */
     name?: string;
+    /**
+     * Marketplace name written into the generated repo-root registries' top-level `name` (and used
+     * for the registries' `owner.name`). This is the identity host platforms register the
+     * marketplace under, and it MUST be unique across marketplaces — two marketplaces sharing a name
+     * collide on install, with the later one shadowing/stranding the earlier one's plugins.
+     *
+     * Distinct from {@link InitOptions.name} (the `package.json` name). When omitted, `runInit`
+     * resolves a default at the I/O boundary (`${USER}-ai-plugins`, falling back to `my-ai-plugins`
+     * when `USER` is unset). `init-template.ts` is a pure function of its inputs, so the resolved
+     * value is passed in rather than read from the environment there.
+     */
+    marketplaceName?: string;
+    /**
+     * Version of `@ai-plugin-marketplace/cli` to pin the generated `package.json`'s `cli`
+     * dev dependency to (as `^<cliVersion>`). The cli entrypoint supplies its own version here; cli
+     * and core ship independently and may differ (e.g. `cli 0.1.1` ships with `core 0.2.0`). When
+     * omitted, falls back to core's own version (the historical lockstep assumption).
+     */
+    cliVersion?: string;
+}
+/**
+ * Options for {@link refreshScaffold}.
+ *
+ * @public
+ */
+export interface RefreshOptions {
+    /**
+     * Overwrite toolkit-owned scaffold files even when their on-disk content has diverged from what
+     * the toolkit last wrote (i.e. the user edited them). Without this, diverged files are reported
+     * as conflicts and left untouched.
+     */
+    force?: boolean;
+}
+/**
+ * Per-file outcome of a {@link refreshScaffold} run. Returned (one per managed scaffold file) so
+ * the CLI can report what changed without re-deriving it.
+ *
+ * @public
+ */
+export interface RefreshOutcome {
+    /** Repo-relative POSIX path of the managed scaffold file. */
+    path: string;
+    /**
+     * - `updated` — content changed and was rewritten (file was pristine or `--force`).
+     * - `unchanged` — already matched the current render; nothing written.
+     * - `recreated` — file was missing and was written from the render.
+     * - `conflict` — on-disk content diverged from the recorded hash; left untouched (no `--force`).
+     * - `overwritten` — diverged but rewritten because `--force` was set.
+     */
+    status: 'updated' | 'unchanged' | 'recreated' | 'conflict' | 'overwritten';
 }
 /**
  * Options for {@link migrate}.

package/dist/pipeline/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pipeline/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,oEAOiB,CAAC;AAmBzC;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,EAAE,QAAQ,CAAC;CAClB;AAKD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,0BAA0B,GAC1B,WAAW,GACX,sBAAsB,GACtB,yBAAyB,GACzB,0BAA0B,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAKD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC9B,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;CAC5E;AAKD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,MAAM,EAAE,sBAAsB,GAAG,SAAS,GAAG,QAAQ,CAAC;IACtD,mBAAmB;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAKD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,4DAA4D;IAC5D,gBAAgB,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC5D,wFAAwF;IACxF,WAAW,EAAE;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CAC1D"}

package/dist/pipeline/validate.d.ts

@@ -7,6 +7,7 @@
  *
  * @see docs/specs/architecture.md §6, §8.1, §10.1, §10.2
  */
+import type { AipmWorkspace } from '../config.js';
 import type { Finding, TargetId, ValidateOptions, ValidationResult } from './types.js';
 /**
  * Minimum required artifacts for each target. Missing any of these when the target is
@@ -14,6 +15,17 @@ import type { Finding, TargetId, ValidateOptions, ValidationResult } from './typ
  * Vercel requires at least one skills/<name>/SKILL.md — handled specially below.
  */
 export declare const TARGET_MIN_REQUIRED: Record<TargetId, string[]>;
+/**
+ * Repo-level check: warn (SOFT) when the effective marketplace `name` or `owner.name` is still a
+ * template placeholder. A placeholder name collides with the upstream `ai-plugin-marketplace`
+ * marketplace (or any other fork that kept the default) — when two marketplaces register under the
+ * same name, the later install shadows/strands the earlier's plugins. Emitting nothing when no
+ * marketplace metadata is declared (an empty `aipm init` repo before any name is set).
+ *
+ * Always SOFT: this is advice the author should act on, never a reason to fail the build (it does
+ * not flip `passed`).
+ */
+export declare function checkDefaultMarketplaceName(repoRoot: string, workspace: AipmWorkspace | undefined): Finding[];
 /**
  * Validate an already-loaded `aipm.config.ts` value against AipmConfig's Zod schema.
  * Loading from disk is the pipeline orchestrator's job (Stage 5). Here we only validate shape.

package/dist/pipeline/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/pipeline/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsCH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiCvF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,CAO1D,CAAC;AAoHF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,CAsBvF;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CA4FX;AAMD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAmGX;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,EAAE,CAgD9F;AAoDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CA0FX;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAOX;AAyZD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,eAAe,GAAG;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,OAAO,CAAC,gBAAgB,CAAC,CAoI3B"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/pipeline/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiCvF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,CAO1D,CAAC;AA8LF;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GAAG,SAAS,GACnC,OAAO,EAAE,CAuBX;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,EAAE,CAsBvF;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CA4FX;AAMD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAmGX;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,EAAE,CAgD9F;AAoDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CA0FX;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAOX;AAyZD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,eAAe,GAAG;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,OAAO,CAAC,gBAAgB,CAAC,CA+I3B"}

package/dist/pipeline/validate.js

@@ -138,6 +138,98 @@ function hard(code, plugin, message, hint) {
     return { severity: 'hard', code, plugin, message, ...(hint !== undefined ? { hint } : {}) };
 }
 // ---------------------------------------------------------------------------
+// Default / placeholder marketplace name check
+// ---------------------------------------------------------------------------
+/**
+ * Marketplace `name` values that are template placeholders, not a real identity. `ai-plugin-marketplace`
+ * is the upstream template repo's own name (a fork that never renamed collides with upstream);
+ * `my-ai-plugins` is the placeholder the template ships and the fallback `aipm init` writes when
+ * `$USER` is unset (intentionally flagged so the author is nudged to pass `--name`).
+ */
+const PLACEHOLDER_MARKETPLACE_NAMES = new Set([
+    'ai-plugin-marketplace',
+    'my-ai-plugins',
+]);
+/**
+ * Marketplace `owner.name` values that are template placeholders rather than a real owner.
+ */
+const PLACEHOLDER_OWNER_NAMES = new Set([
+    'AI Plugin Marketplace Template',
+    'Your Name',
+]);
+/** Schema for the marketplace metadata this check reads from a generated registry JSON. */
+const registryMetadataSchema = z
+    .object({
+    name: z.string().optional(),
+    owner: z.object({ name: z.string().optional() }).loose().optional(),
+})
+    .loose();
+/**
+ * Resolve the repo's effective marketplace identity for the default-name check. Prefers the
+ * authored `aipm.workspace.ts` (which `runValidate` already loaded) and falls back to reading a
+ * committed repo-root registry's top-level `name`/`owner.name` (the hand-authored / `aipm init`
+ * path, where no workspace exists). The first managed registry that parses and declares a `name`
+ * OR an `owner.name` wins; all generated registries carry the same marketplace identity, so any
+ * one is representative.
+ */
+function resolveMarketplaceIdentity(repoRoot, workspace) {
+    if (workspace !== undefined) {
+        const { marketplace } = workspace;
+        return {
+            name: marketplace.name,
+            ...(marketplace.owner !== undefined ? { ownerName: marketplace.owner.name } : {}),
+        };
+    }
+    for (const registryPath of managedRegistryPaths(repoRoot)) {
+        if (!fs.existsSync(registryPath))
+            continue;
+        const parsed = registryMetadataSchema.safeParse(tryReadJson(registryPath));
+        if (!parsed.success)
+            continue;
+        const { name, owner } = parsed.data;
+        // Only treat this registry as the identity source once it declares a `name` or an `owner.name`;
+        // an empty `{ "plugins": [] }` registry carries no identity, so keep scanning the others.
+        if (name === undefined && owner?.name === undefined)
+            continue;
+        return {
+            ...(name !== undefined ? { name } : {}),
+            ...(owner?.name !== undefined ? { ownerName: owner.name } : {}),
+        };
+    }
+    return {};
+}
+/**
+ * Repo-level check: warn (SOFT) when the effective marketplace `name` or `owner.name` is still a
+ * template placeholder. A placeholder name collides with the upstream `ai-plugin-marketplace`
+ * marketplace (or any other fork that kept the default) — when two marketplaces register under the
+ * same name, the later install shadows/strands the earlier's plugins. Emitting nothing when no
+ * marketplace metadata is declared (an empty `aipm init` repo before any name is set).
+ *
+ * Always SOFT: this is advice the author should act on, never a reason to fail the build (it does
+ * not flip `passed`).
+ */
+export function checkDefaultMarketplaceName(repoRoot, workspace) {
+    const { name, ownerName } = resolveMarketplaceIdentity(repoRoot, workspace);
+    const findings = [];
+    if (name !== undefined && PLACEHOLDER_MARKETPLACE_NAMES.has(name)) {
+        findings.push({
+            severity: 'soft',
+            code: 'default-marketplace-name',
+            message: `Marketplace name '${name}' is a template default. Two marketplaces registered under the same name collide on install — the later one shadows/strands the earlier one's plugins (including the upstream 'ai-plugin-marketplace').`,
+            hint: "Rename it to a unique value (convention: '<your-handle>-ai-plugins'): set marketplace.name in aipm.workspace.ts, or the top-level `name` in the repo-root registries (.claude-plugin/.cursor-plugin/marketplace.json) when there is no workspace. New repos can pass `aipm init --name <name>`.",
+        });
+    }
+    if (ownerName !== undefined && PLACEHOLDER_OWNER_NAMES.has(ownerName)) {
+        findings.push({
+            severity: 'soft',
+            code: 'default-marketplace-name',
+            message: `Marketplace owner name '${ownerName}' is a template default, not a real owner.`,
+            hint: 'Set marketplace.owner.name in aipm.workspace.ts (or the repo-root registries) to your name or organization.',
+        });
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
 // validateEnvelopeShape
 // ---------------------------------------------------------------------------
 /**
@@ -894,7 +986,17 @@ export async function runValidate(targetPath, opts) {
             findings.push(...checkFreshness(pluginDir, distDir, envelope, ci));
         }
     }
-    // ── 6. Repo-level generation checks (only when generation is opted in) ──────
+    // ── 6. Repo-level default/placeholder marketplace-name check (always SOFT) ──
+    // Marketplace identity is a REPO-level concern, so this runs only when validating a repo root
+    // (not a single plugin directory — that path stays scoped to the one plugin and short-circuits
+    // on envelope-invalid). Independent of registry generation: the effective name comes from
+    // `aipm.workspace.ts` when present, else from a committed repo-root registry's top-level
+    // `name`/`owner.name`. A placeholder name collides with the upstream marketplace and strands
+    // plugins, so warn — but never fail (soft, does not flip `passed`).
+    if (path.resolve(targetPath) === repoRoot) {
+        findings.push(...checkDefaultMarketplaceName(repoRoot, workspace));
+    }
+    // ── 7. Repo-level generation checks (only when generation is opted in) ──────
     // Registries AND single-artifact-host root artifacts are repo-scoped, so these run once per repo
     // against EVERY plugin under the repo root — not just the plugins in `pluginDirs` (length-1 for
     // single-plugin input). That mirrors how `runBuild` regenerates the repo-complete output, so a