@avocadostudio-ai/orchestrator-core 0.2.3 → 0.3.1

package/dist/agent/sites-agent-tools.js

@@ -19,7 +19,7 @@ import { scopedSessionKey, setPage, bumpVersion, getSiteConfig, setSiteConfig }
 import { listImages as listGdriveImages, downloadImage as downloadGdriveImage, isGdriveConfigured, resolveGdriveFolderId, fileNameToAlt, } from "../image/gdrive-client.js";
 import sharp from "sharp";
 import { sanitizeSiteId, monorepoRoot, findAvailablePort, patchGlobalsCssVars, validateAndCorrectProps, fixFooterLinks, analyzeCodebase, cloneRepo, detectSitePort, startAndWaitForDevServer, getDraftModeSecret, packageJson, nextConfigTs, tsconfigJson, postcssConfig, layoutTsx, globalsCss, defaultsTs, editorApiRoute, pageTsx, hybridPageTsx, blocksRegisterTsx, samplePagesJson, defaultLogoSvg, faviconSvg, } from "./sites-agent-shared.js";
-/** Convert a package name like "villa-puravida-web" → "Villa Puravida Web" */
+/** Convert a package name like "coastal-villa-web" → "Coastal Villa Web" */
 function humanizePkgName(name) {
     return name
         .replace(/^@[^/]+\//, "") // strip scope

package/dist/chat/changelog-coverage-validator.d.ts

@@ -34,4 +34,16 @@ export type ChangelogCoverageResult = {
 export declare function validateChangelogCoverage(args: {
     plan: EditPlan;
     draft: Map<string, PageDoc>;
+    /**
+     * Trailing `change_log` entries that describe the turn rather than an op —
+     * currently just the note the hallucination validator appends when it strips
+     * a prop the block does not have.
+     *
+     * They are neither counted against `ops.length` nor trimmed. Without this the
+     * arithmetic below sees N ops and N+1 entries, calls the note the planner
+     * over-describing itself, and deletes it — and that note is the only place
+     * the user is told a field they asked for does not exist. Two validators
+     * twenty lines apart, one erasing the other's output.
+     */
+    notes?: string[];
 }): ChangelogCoverageResult;

package/dist/chat/changelog-coverage-validator.js

@@ -156,6 +156,22 @@ function describeOp(op, draft) {
  */
 export function validateChangelogCoverage(args) {
     const { plan, draft } = args;
+    /*
+     * Split the notes off the tail, run the op-vs-narration arithmetic on what is
+     * left, and put them back. `notes` are appended last by construction, so this
+     * is a suffix check rather than a search.
+     */
+    const notes = [];
+    for (const note of [...(args.notes ?? [])].reverse()) {
+        if (plan.change_log[plan.change_log.length - 1] !== note)
+            continue;
+        plan.change_log = plan.change_log.slice(0, -1);
+        notes.unshift(note);
+    }
+    const restoreNotes = () => {
+        if (notes.length > 0)
+            plan.change_log = [...plan.change_log, ...notes];
+    };
     const empty = {
         plan,
         missingCount: 0,
@@ -165,8 +181,10 @@ export function validateChangelogCoverage(args) {
         fieldMislabelCount: 0,
         relabeledEntries: []
     };
-    if (plan.intent !== "edit_plan")
+    if (plan.intent !== "edit_plan") {
+        restoreNotes();
         return empty;
+    }
     const opCount = plan.ops.length;
     // Field-level pass (#13): an update_props entry can be the right COUNT yet name
     // the wrong field. Relabel each mislabeled update_props entry from the op's
@@ -190,13 +208,16 @@ export function validateChangelogCoverage(args) {
     }
     const changeCount = plan.change_log.length;
     if (changeCount === opCount) {
+        restoreNotes();
         return { ...empty, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
     }
     // Empty ops list with non-empty change_log is almost always a planner
     // confusion (intent should have been content_answer). Leave it for
     // higher-level handling rather than wiping the user-facing copy here.
-    if (opCount === 0)
+    if (opCount === 0) {
+        restoreNotes();
         return empty;
+    }
     if (changeCount < opCount) {
         const missingCount = opCount - changeCount;
         const synthesizedEntries = [];
@@ -204,6 +225,7 @@ export function validateChangelogCoverage(args) {
             synthesizedEntries.push(describeOp(plan.ops[i], draft));
         }
         plan.change_log = [...plan.change_log, ...synthesizedEntries];
+        restoreNotes();
         return { plan, missingCount, synthesizedEntries, extraCount: 0, droppedEntries: [], fieldMislabelCount: relabeledEntries.length, relabeledEntries };
     }
     // changeCount > opCount: planner described more changes than it emitted ops
@@ -211,5 +233,6 @@ export function validateChangelogCoverage(args) {
     const extraCount = changeCount - opCount;
     const droppedEntries = plan.change_log.slice(opCount);
     plan.change_log = plan.change_log.slice(0, opCount);
+    restoreNotes();
     return { plan, missingCount: 0, synthesizedEntries: [], extraCount, droppedEntries, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
 }

package/dist/chat/chat-pipeline.js

@@ -4,7 +4,7 @@ import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, isGenerating
 import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isAdviceQuery, adviceResponse, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
 import { isLikelyClarificationFollowUp } from "../nlp/intent-helpers.js";
 import { versions, pendingClarificationBySession, chatHistoryBySession, pendingApprovalPlanBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage } from "../state/session-state.js";
-import { toErrorDetail, isNoEffectiveChangeError, classifyGuardrailError, formatValidationError, isDeterministicRepairEligible, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
+import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isDeterministicRepairEligible, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
 import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
 import { generatePlanWithOpenAI, isPlannerOutputError, isStrictJsonResponseEnabled, parseIntentWithOpenAI } from "./planner.js";
@@ -1101,6 +1101,14 @@ export async function runChatPipeline(ctx, body, options) {
     const respondFromPlan = async (plan, source, applyMode = "apply_now", optionsOverride, plannerTier) => {
         if (plannerTier)
             activePlannerTier = plannerTier;
+        /*
+         * The note the hallucination validator writes when it strips a prop the
+         * block does not have, hoisted so the no-effective-change handler far below
+         * can reach it. That handler replaces `summary_for_user` wholesale, and a
+         * plan whose every prop was stripped lands there — so without this the one
+         * true sentence written about the turn is the one the user never sees.
+         */
+        let strippedPropsNote;
         const usageFields = planUsage ? {
             inputTokens: planUsage.inputTokens,
             outputTokens: planUsage.outputTokens,
@@ -1152,6 +1160,7 @@ export async function runChatPipeline(ctx, body, options) {
                 plan: resolvedPlan,
                 draft: getSessionDraft(body.session)
             });
+            strippedPropsNote = hallucinationResult.note;
             if (hallucinationResult.hallucinatedProps.length > 0) {
                 for (const entry of hallucinationResult.hallucinatedProps) {
                     ctx.log.warn({
@@ -1173,7 +1182,9 @@ export async function runChatPipeline(ctx, body, options) {
             // sees the correct count instead of silently approving uncovered ops.
             const changelogResult = validateChangelogCoverage({
                 plan: resolvedPlan,
-                draft: getSessionDraft(body.session)
+                draft: getSessionDraft(body.session),
+                // Not an op narration, so not something to trim for over-describing.
+                notes: hallucinationResult.note ? [hallucinationResult.note] : undefined
             });
             if (changelogResult.missingCount > 0) {
                 ctx.log.warn({
@@ -2540,13 +2551,47 @@ export async function runChatPipeline(ctx, body, options) {
                     ...plannerContextTelemetryFields,
                     ...timingFields()
                 });
+                /*
+                 * Two facts arrive here and only one of them is "your content is
+                 * already correct".
+                 *
+                 * The engine throws "All update patches matched existing values" when
+                 * the values genuinely matched, and "Edit plan produced no changes"
+                 * when the plan had nothing left to apply — which is what a plan looks
+                 * like after every prop in it was stripped as unsupported by the block.
+                 * Answering both with `status: "applied"` and "already up to date"
+                 * tells an author their content is fine when their request was in fact
+                 * dropped, and it is the shape of failure nobody reports, because the
+                 * product said it worked.
+                 *
+                 * The two sibling branches in this file already draw this line — the
+                 * approval-gate no-op at `planPreview.appliedCount === 0` and the
+                 * empty-plan branch that refuses to claim up-to-date-ness for an
+                 * `edit_plan` intent. This was the third one, and it was the one an
+                 * adopter hit.
+                 */
+                /*
+                 * A note from the hallucination validator outranks both engine
+                 * messages. It means this turn asked for a field the block does not
+                 * have, which is a better answer than either of them and the only one
+                 * that names the block — and it is true whichever message the engine
+                 * happened to throw, since an op stripped to an empty patch can land in
+                 * `skippedOps` and read as "matched existing values".
+                 */
+                const noopSummary = strippedPropsNote ??
+                    (isAlreadyCurrentError(reason)
+                        ? "No changes needed — that content is already set."
+                        : "I couldn't make that change — it isn't supported on this block. Try a different field or wording.");
                 return {
                     done: true,
                     response: {
                         code: 200,
                         payload: withDebugPayload({
-                            status: "applied",
-                            summary: "No changes needed. That content is already up to date.",
+                            // `info`, not `applied`: nothing was applied either way, and the
+                            // approval-gate branch above has answered `info` for the same
+                            // fact since it was written.
+                            status: "info",
+                            summary: noopSummary,
                             changes: [],
                             mentionedSlugs: [effectiveSlug],
                             previewVersion: versions.get(body.session) ?? 0,

package/dist/chat/hallucination-validator.d.ts

@@ -19,6 +19,11 @@ export type HallucinatedProp = {
 export type HallucinationValidationResult = {
     plan: EditPlan;
     hallucinatedProps: HallucinatedProp[];
+    /**
+     * The user-facing note appended to `summary_for_user` and `change_log`,
+     * when props were stripped. Absent when nothing was.
+     */
+    note?: string;
 };
 /**
  * Scan every `update_props` op in the plan, strip patch keys that are not

package/dist/chat/hallucination-validator.js

@@ -105,6 +105,19 @@ export function validateAndStripHallucinatedProps(args) {
         const summary = plan.summary_for_user?.trimEnd() ?? "";
         plan.summary_for_user = summary.length > 0 ? `${summary}\n\n${note}` : note;
         plan.change_log = [...plan.change_log, note];
+        /*
+         * Returned as well as appended, for two callers that both need it back.
+         *
+         * The changelog-coverage validator runs next and trims trailing entries
+         * when there are more of them than ops — and this note is always the last
+         * entry, so it was always the one trimmed. It has to be told which entry is
+         * a note rather than an op narration.
+         *
+         * And the no-effective-change handler replaces `summary_for_user` wholesale
+         * with a canned line, which is exactly the case where this note is the only
+         * true thing anyone wrote about the turn.
+         */
+        return { plan, hallucinatedProps, note };
     }
     return { plan, hallucinatedProps };
 }

package/dist/cms/adapter.d.ts

@@ -57,6 +57,41 @@ export type CmsPublishResult = void | {
     error?: string;
     unsupported?: string[];
 };
+/**
+ * One asset from a CMS's media library, in the shape the editor's image picker
+ * renders. Deliberately the smallest projection that a picker needs: an
+ * identity, something to show, something to insert, and something to put in an
+ * `alt`. Anything richer would be a per-CMS shape again.
+ */
+export interface CmsMediaItem {
+    /** Stable id in the source store. Used as the picker's selection key. */
+    id: string;
+    /** Human-facing filename or title, if the store has one. */
+    name?: string;
+    /** Full-size URL to insert into the page. Omitted only if the store has none. */
+    imageUrl?: string;
+    /** Grid thumbnail. May be the same URL as `imageUrl` when no derivative exists. */
+    thumbUrl: string;
+    /** Alt text the store already holds, so the editor does not invent one. */
+    alt?: string;
+}
+/** One page of a media-library search. */
+export interface CmsMediaQuery {
+    /** Free-text filter. Empty or absent means "everything, newest first". */
+    query?: string;
+    /** 1-based page number. */
+    page: number;
+    /** Items per page. */
+    limit: number;
+}
+/** What `getMedia` returns: the page, and how many there are in total. */
+export interface CmsMediaPage {
+    items: CmsMediaItem[];
+    /** Total pages for this query, so the picker knows whether to offer "load more". */
+    totalPages: number;
+    /** Display name for the tab, e.g. "Sanity". Defaults to the adapter's `id`. */
+    label?: string;
+}
 /**
  * Which side of a CMS's draft/published split a read wants.
  *
@@ -146,6 +181,24 @@ export interface CmsAdapter {
      * unreachable, so it cannot be a method that reads upstream.
      */
     readonly capabilities?: CmsCapabilities;
+    /**
+     * Optional media-library read, for the editor's image picker.
+     *
+     * The picker used to reach the CMS from the browser, over a closed union of
+     * three providers compiled into the editor app. That made the image picker
+     * the one part of an integration that could not be integrated: a site could
+     * bring its own adapter, its own blocks and its own publish handler, and
+     * still had no way to bring its own images short of a change to Avocado.
+     *
+     * Implement it and the tab appears. Leave it off and it does not — silence
+     * means no here, the same way it does for `perspectives`, because a picker
+     * that offers a tab it cannot fill is worse than no tab.
+     *
+     * `cmsMediaSource()` in `./media-sources.ts` implements this for Contentful,
+     * Sanity and Strapi if one of those is what you have; it is a helper, not a
+     * requirement, and nothing in the route path knows it exists.
+     */
+    getMedia?(query: CmsMediaQuery): Promise<CmsMediaPage>;
 }
 /**
  * Per-operation capability declaration. Every field is tri-state, and the
@@ -203,6 +256,15 @@ export interface ResolvedCapabilities {
      * knows not to conclude "nothing is pending" from an empty diff.
      */
     readsDraftPerspective: boolean;
+    /**
+     * True when the adapter can list the CMS's media library; derived from the
+     * presence of `getMedia`, never declared as a capability.
+     *
+     * The editor reads it to decide whether to offer a CMS tab in the image
+     * picker at all, which is why it is derived rather than declared: a tab that
+     * opens onto a method nobody implemented is a worse answer than no tab.
+     */
+    readsMedia: boolean;
     /**
      * The subset the adapter actually declared. A caller that needs to
      * distinguish "this site says no" from "nobody said" reads this; everything

package/dist/cms/adapter.js

@@ -14,6 +14,7 @@ export function resolveCapabilities(adapter, override) {
         publishesUpstream: typeof adapter?.onPublish === "function",
         // `=== true`, not truthiness: an adapter that says nothing has not said yes.
         readsDraftPerspective: adapter?.perspectives === true,
+        readsMedia: typeof adapter?.getMedia === "function",
         declared
     };
 }

package/dist/cms/bootstrap.d.ts

@@ -43,12 +43,36 @@ export interface CmsBootstrapCache {
      * clone and no extra adapter read. Re-reading upstream at publish time would
      * cost 45 sequential CMS calls on the integration that motivated this.
      *
-     * Bounded and best-effort by construction. It is null after a restart that
-     * reloaded the draft from SQLite (the seed never ran), and it is evicted
-     * FIFO past `maxBaselines`, so a caller must treat null as "no baseline
-     * available" and never as "the site was empty".
+     * Bounded and best-effort by construction. A restart that reloads the draft
+     * from SQLite skips the seed but not the baseline — `ensure` re-reads the
+     * adapter for it, which is sound because nothing was published in between —
+     * but it is still evicted FIFO past `maxBaselines`, and still null when the
+     * adapter read failed. A caller must treat null as "no baseline available"
+     * and never as "the site was empty".
      */
     baselineFor(session: string): PageDoc[] | null;
+    /**
+     * Discard this session's draft and seed it again from the adapter.
+     *
+     * `ensure()` is deliberately once-per-session: it exists to not clobber a
+     * draft that SQLite already holds. That is right for every ordinary request
+     * and wrong for the one case an integrator hits constantly while building an
+     * adapter — they change how their projection shapes pages, and the
+     * orchestrator keeps serving the shapes it read before the change. The only
+     * way out used to be deleting `.data/` and restarting the process, which is
+     * a much larger hammer than the problem.
+     *
+     * **This destroys unpublished edits in the session draft**, which is what
+     * makes it a separate, explicitly-requested call rather than something
+     * `ensure()` could decide to do on its own.
+     *
+     * It discards nothing until the adapter has answered: a failed read rejects
+     * and leaves the draft, the baseline and the attempt marker untouched, so a
+     * reseed against a CMS that happens to be down cannot cost anyone their
+     * work. A read that succeeds and returns no pages *is* an answer, and empties
+     * the draft accordingly.
+     */
+    reseed(session: string, adapter: CmsAdapter | null | undefined, log: Logger): Promise<void>;
     /** Test helper — drop all remembered state. */
     reset(): void;
     /** Inspection — number of remembered attempts (post-eviction). */

package/dist/cms/bootstrap.js

@@ -129,7 +129,31 @@ export function createCmsBootstrapCache(opts = {}) {
             return existing;
         const promise = (async () => {
             const draft = getSessionDraft(session);
-            if (draft.size > 0)
+            /*
+             * A draft that is already populated came from SQLite, not from us, and
+             * for a long time that was the end of the matter: seeding was the only
+             * thing this function did, so a loaded draft meant there was nothing to
+             * do. But the seed also produces the publish baseline, and that made the
+             * early return silently disable publishing. The draft survives a
+             * restart, so `ensure` returned here, so `rememberBaseline` never ran, so
+             * `context.published` was `undefined` for the rest of the process's life
+             * — and a publisher written the documented way (diff against the
+             * baseline, refuse when there is none) can then never publish again.
+             * Restarting to fix it is the one thing guaranteed not to.
+             *
+             * So the two jobs are now separate. A loaded draft still skips the seed;
+             * it no longer skips the baseline. Recovering it costs one
+             * `getPages()` — the same call the seed would have made, usually served
+             * from the warm cache — and it is correct to read upstream for it,
+             * because nothing has been published: the CMS still holds exactly the
+             * pre-edit content the lost baseline was a copy of.
+             *
+             * This is the same shape as the `setSessionCapabilities` hoist above.
+             * Anything the seed produces besides the draft has to survive a restart
+             * that reloads the draft.
+             */
+            const seeded = draft.size > 0;
+            if (seeded && baselines.has(session))
                 return; // finally-block records the attempt
             try {
                 const warmed = warmedPages(adapter);
@@ -139,13 +163,17 @@ export function createCmsBootstrapCache(opts = {}) {
                     return;
                 }
                 /*
-                 * Keep the pre-edit copy. The pages are already being cloned into the
-                 * draft, so a baseline for the eventual publish diff costs one more
+                 * Keep the pre-edit copy. When we are also seeding, the pages are
+                 * already being cloned into the draft, so the baseline costs one more
                  * clone and — the point — no second adapter read. Re-reading upstream
                  * at publish time is 45 sequential CMS calls on the integration that
                  * motivated this.
                  */
                 rememberBaseline(session, pages.map((page) => structuredClone(page)));
+                if (seeded) {
+                    log.info({ session, adapter: adapter.id, count: pages.length }, "cms-bootstrap: recovered publish baseline for a draft reloaded from storage");
+                    return;
+                }
                 for (const page of pages) {
                     const copy = structuredClone(page);
                     ensureHeroImageProps(copy);
@@ -174,9 +202,48 @@ export function createCmsBootstrapCache(opts = {}) {
             inFlight.delete(session);
         }
     }
+    async function reseed(session, adapter, log) {
+        if (!adapter)
+            return;
+        setSessionCapabilities(session, resolveCapabilities(adapter, capabilityOverride));
+        // Wait out a seed already in flight, so the discard below cannot land
+        // between that seed's adapter read and its writes and leave half a draft.
+        const existing = inFlight.get(session);
+        if (existing)
+            await existing.catch(() => { });
+        /*
+         * Read before discarding, not after. Clearing the draft and then calling
+         * `ensure` reads well and fails badly: `ensure` swallows an adapter error
+         * and marks the session attempted on the way out, so an adapter that was
+         * merely down turned a stale draft into an empty one that nothing would
+         * ever retry. The caller asked to replace the draft with what the adapter
+         * says; if the adapter says nothing, there is no replacement to make and
+         * the right answer is to leave the session exactly as we found it.
+         *
+         * This deliberately does not consult the warmed list. That list is a
+         * cold-start bridge and may predate whatever change prompted the reseed —
+         * serving it here would return the exact staleness we were asked to clear.
+         */
+        const pages = await adapter.getPages({ perspective: "draft" });
+        const draft = getSessionDraft(session);
+        const discarded = draft.size;
+        draft.clear();
+        for (const page of pages) {
+            const copy = structuredClone(page);
+            ensureHeroImageProps(copy);
+            draft.set(copy.slug, copy);
+        }
+        rememberBaseline(session, pages.map((page) => structuredClone(page)));
+        markAttempted(session);
+        warmEntry = null;
+        bumpVersion(session);
+        schedulePersistState(log);
+        log.info({ session, adapter: adapter.id, discarded, count: pages.length }, "cms-bootstrap: reseeded session draft from the adapter");
+    }
     return {
         ensure,
         warm,
+        reseed,
         baselineFor(session) {
             return baselines.get(session) ?? null;
         },

package/dist/cms/index.d.ts

@@ -1,5 +1,6 @@
-export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./adapter.ts";
+export type { CmsAdapter, CmsMediaItem, CmsMediaPage, CmsMediaQuery, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./adapter.ts";
 export { resolveCapabilities } from "./adapter.ts";
 export { jsonFileAdapter, type JsonFileAdapterOptions } from "./json-file-adapter.ts";
 export { editorApiAdapter, type EditorApiAdapterOptions } from "./editor-api-adapter.ts";
 export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, type CmsBootstrapCache, type CmsBootstrapCacheOptions, warmSessionBootstrap } from "./bootstrap.ts";
+export { cmsMediaSource, cmsMediaLabel, mediaSourceFromUnknown, type CmsMediaSource, type CmsMediaSourceConfig } from "./media-sources.ts";

package/dist/cms/index.js

@@ -2,3 +2,4 @@ export { resolveCapabilities } from "./adapter.js";
 export { jsonFileAdapter } from "./json-file-adapter.js";
 export { editorApiAdapter } from "./editor-api-adapter.js";
 export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, warmSessionBootstrap } from "./bootstrap.js";
+export { cmsMediaSource, cmsMediaLabel, mediaSourceFromUnknown } from "./media-sources.js";

package/dist/cms/json-file-adapter.js

@@ -2,7 +2,7 @@
 //
 // Smallest possible adapter. Suitable for sites that keep their content as
 // a checked-in JSON array (the shape the orchestrator + blocks already
-// understand). villa-puravida-web's lib/published-content.json is the
+// understand). A consumer site's lib/published-content.json is the
 // canonical example.
 //
 // If `writeOnPublish` is true, onPublish() will overwrite the file with the

package/dist/cms/media-sources.d.ts

@@ -0,0 +1,49 @@
+import type { CmsMediaPage, CmsMediaQuery } from "./adapter.ts";
+/** Connection details for one of the built-in media readers. */
+export type CmsMediaSourceConfig = {
+    provider: "contentful";
+    spaceId: string;
+    deliveryToken: string;
+    environment?: string;
+} | {
+    provider: "sanity";
+    projectId: string;
+    dataset?: string;
+    token?: string;
+} | {
+    provider: "strapi";
+    url: string;
+    token?: string;
+};
+/** A media reader: the exact shape of `CmsAdapter.getMedia`. */
+export type CmsMediaSource = (query: CmsMediaQuery) => Promise<CmsMediaPage>;
+/** Display name for a provider id, for the picker's tab. */
+export declare function cmsMediaLabel(provider: CmsMediaSourceConfig["provider"]): string;
+/**
+ * Build a media reader from connection details.
+ *
+ * ```ts
+ * export function sanityAdapter(): CmsAdapter {
+ *   return {
+ *     id: "sanity",
+ *     getPages: …,
+ *     getMedia: cmsMediaSource({ provider: "sanity", projectId, dataset })
+ *   }
+ * }
+ * ```
+ *
+ * Every reader answers an empty page rather than throwing when the upstream
+ * call fails: a picker tab that renders nothing is recoverable, and a rejected
+ * promise inside a modal is not.
+ */
+export declare function cmsMediaSource(config: CmsMediaSourceConfig): CmsMediaSource;
+/**
+ * Build a reader from an untrusted object, or `null` if it is not one of the
+ * three shapes.
+ *
+ * The editor sends this over the wire, so every field is checked rather than
+ * asserted. A partially-filled form — the drawer creates `{ provider:
+ * "sanity", projectId: "" }` the moment the provider is picked — must read as
+ * "not configured" and not as a reader that will 404 on every request.
+ */
+export declare function mediaSourceFromUnknown(raw: unknown): CmsMediaSource | null;

package/dist/cms/media-sources.js

@@ -0,0 +1,182 @@
+const LABELS = {
+    contentful: "Contentful",
+    sanity: "Sanity",
+    strapi: "Strapi"
+};
+/** Display name for a provider id, for the picker's tab. */
+export function cmsMediaLabel(provider) {
+    return LABELS[provider];
+}
+const EMPTY = (label) => ({ items: [], totalPages: 0, label });
+/**
+ * Build a media reader from connection details.
+ *
+ * ```ts
+ * export function sanityAdapter(): CmsAdapter {
+ *   return {
+ *     id: "sanity",
+ *     getPages: …,
+ *     getMedia: cmsMediaSource({ provider: "sanity", projectId, dataset })
+ *   }
+ * }
+ * ```
+ *
+ * Every reader answers an empty page rather than throwing when the upstream
+ * call fails: a picker tab that renders nothing is recoverable, and a rejected
+ * promise inside a modal is not.
+ */
+export function cmsMediaSource(config) {
+    switch (config.provider) {
+        case "contentful": return (q) => contentfulMedia(config, q);
+        case "sanity": return (q) => sanityMedia(config, q);
+        case "strapi": return (q) => strapiMedia(config, q);
+    }
+}
+// ---------------------------------------------------------------------------
+// Contentful — Delivery API, `skip`/`limit` paging, `total` in the envelope.
+// ---------------------------------------------------------------------------
+async function contentfulMedia(config, { query, page, limit }) {
+    const label = LABELS.contentful;
+    const env = config.environment ?? "master";
+    const params = new URLSearchParams({
+        access_token: config.deliveryToken,
+        limit: String(limit),
+        skip: String((page - 1) * limit),
+        mimetype_group: "image"
+    });
+    if (query)
+        params.set("query", query);
+    const res = await fetch(`https://cdn.contentful.com/spaces/${config.spaceId}/environments/${env}/assets?${params}`);
+    if (!res.ok)
+        return EMPTY(label);
+    const data = (await res.json());
+    const items = (data.items ?? [])
+        .filter((item) => item.sys?.id && item.fields?.file?.url)
+        .map((item) => {
+        const url = item.fields.file.url;
+        // Contentful returns protocol-relative asset URLs.
+        const fullUrl = url.startsWith("//") ? `https:${url}` : url;
+        return {
+            id: item.sys.id,
+            name: item.fields?.title,
+            alt: item.fields?.description ?? item.fields?.title,
+            imageUrl: fullUrl,
+            thumbUrl: `${fullUrl}?w=200&h=200&fit=thumb`
+        };
+    });
+    return { items, totalPages: Math.ceil((data.total ?? 0) / limit), label };
+}
+// ---------------------------------------------------------------------------
+// Sanity — GROQ, slice paging, a second query for the count.
+// ---------------------------------------------------------------------------
+async function sanityMedia(config, { query, page, limit }) {
+    const label = LABELS.sanity;
+    const dataset = config.dataset ?? "production";
+    const offset = (page - 1) * limit;
+    const end = offset + limit - 1;
+    // GROQ is interpolated, so the filter term is stripped of the two characters
+    // that could close the string literal it lands inside.
+    const safeQuery = (query ?? "").replace(/["\\]/g, "");
+    const filter = safeQuery
+        ? `_type == "sanity.imageAsset" && originalFilename match "*${safeQuery}*"`
+        : `_type == "sanity.imageAsset"`;
+    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] { _id, url, originalFilename, metadata { dimensions } }`;
+    const countGroq = `count(*[${filter}])`;
+    const base = `https://${config.projectId}.api.sanity.io/v2024-01-01/data/query/${dataset}`;
+    const headers = {};
+    if (config.token)
+        headers.authorization = `Bearer ${config.token}`;
+    const [assetsRes, countRes] = await Promise.all([
+        fetch(`${base}?query=${encodeURIComponent(groq)}`, { headers }),
+        fetch(`${base}?query=${encodeURIComponent(countGroq)}`, { headers })
+    ]);
+    if (!assetsRes.ok)
+        return EMPTY(label);
+    const assets = (await assetsRes.json());
+    const count = countRes.ok ? (await countRes.json()).result ?? 0 : 0;
+    return {
+        items: (assets.result ?? []).map((asset) => ({
+            id: asset._id,
+            name: asset.originalFilename,
+            alt: asset.originalFilename,
+            imageUrl: asset.url,
+            thumbUrl: `${asset.url}?w=200&h=200&fit=crop`
+        })),
+        totalPages: Math.ceil(count / limit),
+        label
+    };
+}
+// ---------------------------------------------------------------------------
+// Strapi — upload plugin, page/pageSize paging, count in a response header.
+// ---------------------------------------------------------------------------
+async function strapiMedia(config, { query, page, limit }) {
+    const label = LABELS.strapi;
+    const baseUrl = config.url.replace(/\/+$/, "");
+    const params = new URLSearchParams({
+        "filters[mime][$startsWith]": "image",
+        "pagination[page]": String(page),
+        "pagination[pageSize]": String(limit),
+        sort: "createdAt:desc"
+    });
+    if (query)
+        params.set("filters[name][$containsi]", query);
+    const headers = {};
+    if (config.token)
+        headers.authorization = `Bearer ${config.token}`;
+    const res = await fetch(`${baseUrl}/api/upload/files?${params}`, { headers });
+    if (!res.ok)
+        return EMPTY(label);
+    const data = (await res.json());
+    const absolute = (u) => (u.startsWith("http") ? u : `${baseUrl}${u}`);
+    // The upload endpoint returns a bare array; the count is a header.
+    const totalCount = Number(res.headers.get("x-total-count") ?? data.length);
+    return {
+        items: data.map((file) => ({
+            id: file.documentId ?? String(file.id),
+            name: file.name,
+            alt: file.name,
+            imageUrl: absolute(file.url),
+            thumbUrl: file.formats?.thumbnail?.url ? absolute(file.formats.thumbnail.url) : absolute(file.url)
+        })),
+        totalPages: Math.ceil(totalCount / limit),
+        label
+    };
+}
+/**
+ * Build a reader from an untrusted object, or `null` if it is not one of the
+ * three shapes.
+ *
+ * The editor sends this over the wire, so every field is checked rather than
+ * asserted. A partially-filled form — the drawer creates `{ provider:
+ * "sanity", projectId: "" }` the moment the provider is picked — must read as
+ * "not configured" and not as a reader that will 404 on every request.
+ */
+export function mediaSourceFromUnknown(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    const str = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+    switch (obj.provider) {
+        case "contentful": {
+            const spaceId = str(obj.spaceId);
+            const deliveryToken = str(obj.deliveryToken);
+            if (!spaceId || !deliveryToken)
+                return null;
+            return cmsMediaSource({ provider: "contentful", spaceId, deliveryToken, environment: str(obj.environment) });
+        }
+        case "sanity": {
+            const projectId = str(obj.projectId);
+            if (!projectId)
+                return null;
+            return cmsMediaSource({ provider: "sanity", projectId, dataset: str(obj.dataset), token: str(obj.token) });
+        }
+        case "strapi": {
+            const url = str(obj.url);
+            if (!url)
+                return null;
+            return cmsMediaSource({ provider: "strapi", url, token: str(obj.token) });
+        }
+        default:
+            return null;
+    }
+}

package/dist/handler/create-orchestrator.js

@@ -47,6 +47,7 @@ import { createFeedbackStore } from "../telemetry/feedback-store.js";
 import { consoleLogger } from "../logger.js";
 import { createCmsBootstrapCache } from "../cms/bootstrap.js";
 import { resolveCapabilities } from "../cms/adapter.js";
+import { mediaSourceFromUnknown } from "../cms/media-sources.js";
 import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
 import { checkAuth, resolveAuth } from "./auth.js";
 const defaultModelLookup = () => ({
@@ -122,7 +123,7 @@ async function buildRuntime(config) {
      * Start the adapter's page read now rather than on the first request.
      *
      * `ensure()` is lazy, so without this the first caller pays for the whole
-     * CMS read: Paintball Arena Bern's adapter is 45 sequential Sanity reads
+     * CMS read: a tri-lingual site's adapter is 45 sequential Sanity reads
      * behind a dev-server compile, and the `whoami` an MCP agent opens with took
      * four minutes — long enough that the host times out and the agent reports
      * the site as down. Fire-and-forget by contract: a failed warm logs and is
@@ -229,6 +230,7 @@ const SUPPORTED_ROUTES = [
     "POST /restore/snapshot",
     "DELETE /restore/snapshot",
     "GET /unsplash/search",
+    "POST /media/cms",
     "GET+POST /telemetry/chat/feedback",
     "POST /preview/screenshot",
     "POST /audio/transcribe",
@@ -835,6 +837,10 @@ export function createOrchestrator(config = {}) {
                     unsplash: Boolean(process.env.UNSPLASH_ACCESS_KEY),
                     imageGenerate: hasImageBackend,
                     imageGenerateChat: hasImageBackend,
+                    /* Whether this mount's adapter can list a media library. The
+                     * editor offers the picker's CMS tab on it, so silence hides the
+                     * tab rather than opening one onto a method nobody implemented. */
+                    cmsMedia: runtime.capabilities.readsMedia,
                     agentMode: false
                 },
                 /*
@@ -866,10 +872,24 @@ export function createOrchestrator(config = {}) {
             await runtime.ready;
             const session = url.searchParams.get("session") ?? undefined;
             const siteId = url.searchParams.get("siteId") ?? undefined;
-            const slug = url.searchParams.get("slug") ?? undefined;
-            if (!session || !slug) {
+            const slug = url.searchParams.get("slug");
+            if (!session || slug === null) {
                 return jsonResponse({ error: "session and slug are required" }, { status: 400, cors });
             }
+            /*
+             * `?slug=` is a parameter that is present and empty, and answering
+             * "required" sends the integrator to look for a bug in their query
+             * string. What it actually means is that their projection emitted bare
+             * paths: a slug is a leading-slash path and the home page's is `"/"`.
+             * Every other bare slug resolves by string equality, so the home page is
+             * the only one that fails, and it fails as the site's own 404 rendered
+             * inside the editor iframe — which reads as "my site is broken".
+             */
+            if (slug === "") {
+                return jsonResponse({
+                    error: 'slug must not be empty: a page slug is a path beginning with "/", and the home page is "/" rather than ""'
+                }, { status: 400, cors });
+            }
             const scopedSession = scope(session, siteId);
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
             const page = getPage(scopedSession, slug);
@@ -909,9 +929,25 @@ export function createOrchestrator(config = {}) {
                 })
             }, { status: 200, cors });
         }
-        // Editor bootstrap probe. In library mode the adapter is the source of
-        // truth (already seeded by ensure), so this is effectively a confirm — we
-        // don't clobber the draft with the posted pages.
+        /*
+         * Editor bootstrap probe. In library mode the adapter is the source of
+         * truth (already seeded by ensure), so this is effectively a confirm — we
+         * don't clobber the draft with the posted pages.
+         *
+         * `force` was accepted by the standalone orchestrator and silently dropped
+         * here: the body was read as `{session, siteId}` and nothing else, so a
+         * caller asking to re-read the adapter got the cached page list back with
+         * a 200 and the word "bootstrapped" on it. That is worse than refusing,
+         * because the shape an integrator is in when they send it is "I changed my
+         * projection and the orchestrator is still serving the old shapes" — and
+         * the answer looks like confirmation that it re-read. The documented
+         * escape was deleting `.data/` and restarting.
+         *
+         * It now does what it says, including the destructive half: the session
+         * draft is discarded and rebuilt from the adapter, so unpublished edits in
+         * it are lost. `forced` comes back in the response so a caller can tell
+         * which of the two things happened.
+         */
         if (request.method === "POST" && path === "/draft/bootstrap") {
             const runtime = await getRuntime();
             await runtime.ready;
@@ -924,9 +960,31 @@ export function createOrchestrator(config = {}) {
             }
             const body = (raw ?? {});
             const scopedSession = scope(body.session, body.siteId);
-            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const force = body.force === true;
+            if (force) {
+                try {
+                    await runtime.bootstrapCache.reseed(scopedSession, runtime.adapter, runtime.log);
+                }
+                catch (err) {
+                    /*
+                     * A forced reseed reaches the adapter and can fail there, and the
+                     * one thing this route must not do is answer "bootstrapped" when it
+                     * did not bootstrap — that is the failure being fixed, in a new
+                     * costume. The reseed discards nothing before the read succeeds, so
+                     * the draft is intact and saying so is the useful half of the reply.
+                     */
+                    return jsonResponse({
+                        error: "reseed failed: the adapter could not be read",
+                        detail: err instanceof Error ? err.message : String(err),
+                        draft: "unchanged"
+                    }, { status: 502, cors });
+                }
+            }
+            else {
+                await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            }
             const pages = getSessionPages(scopedSession);
-            return jsonResponse({ status: "bootstrapped", count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
+            return jsonResponse({ status: "bootstrapped", forced: force, count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
         }
         // Site config — drives the page-level nav-label + SEO fields shown in the
         // property panel when no block is selected.
@@ -1389,6 +1447,53 @@ export function createOrchestrator(config = {}) {
             }
             return actionResponse(await restoreSnapshotDelete((raw ?? {})), cors);
         }
+        /*
+         * The CMS tab of the image picker.
+         *
+         * Two callers, one route. A library-mode site whose adapter implements
+         * `getMedia` needs to send nothing: the credentials are already in the
+         * process serving this request. The standalone multi-site orchestrator
+         * wires no adapter at all, so the editor sends the per-site connection
+         * details it holds and the route builds a reader from them.
+         *
+         * The adapter wins when both are available — a site that implemented the
+         * seam meant it, and its own reader can see things a generic one cannot.
+         *
+         * POST rather than GET because the second form carries a token, and a
+         * token in a query string is a token in every access log between here and
+         * the browser.
+         */
+        if (request.method === "POST" && path === "/media/cms") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const query = typeof body.query === "string" ? body.query.trim() : "";
+            const page = Math.max(1, Math.trunc(Number(body.page) || 1));
+            const limit = Math.min(50, Math.max(1, Math.trunc(Number(body.limit) || 20)));
+            const source = typeof runtime.adapter?.getMedia === "function"
+                ? runtime.adapter.getMedia.bind(runtime.adapter)
+                : mediaSourceFromUnknown(body.config);
+            /* No adapter method and no usable config is "this site has no media
+             * library", which is a 404 and not an empty page — the editor hides the
+             * tab on the former and renders an empty grid on the latter. */
+            if (!source)
+                return jsonResponse({ error: "CMS media not configured" }, { status: 404, cors });
+            try {
+                const result = await source({ query: query || undefined, page, limit });
+                return jsonResponse(result, { cors });
+            }
+            catch (error) {
+                runtime.log.warn?.({ err: error }, "[avocado] CMS media read failed");
+                return jsonResponse({ items: [], totalPages: 0 }, { cors });
+            }
+        }
         /* The Unsplash tab of the image picker. Unconfigured answers 404, not an
          * empty result set — "no key" and "no matches" are different answers. */
         if (request.method === "GET" && path === "/unsplash/search") {

package/dist/http/screenshot-actions.d.ts

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/http/screenshot-actions.js

@@ -19,7 +19,7 @@
  * `/preview-draft` is only the *default*, though, and it was hardcoded — which
  * meant this route worked on sites `create-ai-site-editor` scaffolded and on no
  * others. An existing site that wires Avocado into its own app has its own
- * draft route (Paintball Arena Bern's is `/avocado/<lang>/<slug>`), and the
+ * draft route (one such site's is `/avocado/<lang>/<slug>`), and the
  * screenshot an agent took to check its own work photographed that site's 404
  * page. So the path is declarable: per request, per registered site, or via
  * `createOrchestrator({ draftPath })`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createOrchestrator, type CreateOrchestratorConfig, type OrchestratorHandler } from "./handler/create-orchestrator.ts";
 export type { OrchestratorAuth, AuthContext } from "./handler/auth.ts";
-export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./cms/adapter.ts";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, type JsonFileAdapterOptions, type EditorApiAdapterOptions } from "./cms/index.ts";
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, CmsMediaItem, CmsMediaPage, CmsMediaQuery, ResolvedCapabilities } from "./cms/adapter.ts";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaSourceConfig } from "./cms/index.ts";

package/dist/index.js

@@ -18,4 +18,4 @@
 //
 // The Fastify HTTP wrapper lives in apps/orchestrator and imports from here.
 export { createOrchestrator } from "./handler/create-orchestrator.js";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "./cms/index.js";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "./cms/index.js";

package/dist/ops/ops-engine.d.ts

@@ -4,6 +4,23 @@ import type { ContentSource } from "../state/content-source.ts";
 import type { PublishDiff } from "@avocadostudio-ai/shared";
 export declare const toErrorDetail: typeof _unifiedToErrorDetail;
 export declare function isNoEffectiveChangeError(reason: string): boolean;
+/**
+ * Within a no-effective-change, did the stored values already match?
+ *
+ * The engine throws two different things and they are not the same fact:
+ *
+ *   "No effective prop change across plan. All update patches matched
+ *    existing values."   → the content really was already what was asked for
+ *   "Edit plan produced no changes"
+ *                        → the plan had nothing left to apply, which is what
+ *                          happens when every prop in it was stripped as
+ *                          unsupported by the block
+ *
+ * Reporting the second as the first tells the author their content is up to
+ * date when their request was in fact dropped. Both messages are pinned by
+ * `isNoEffectiveChangeError` above, so they are already load-bearing strings.
+ */
+export declare function isAlreadyCurrentError(reason: string): boolean;
 export declare function classifyGuardrailError(reason: string): GuardrailErrorCategory;
 export declare function formatValidationError(reason: string): string;
 export declare function isDeterministicRepairEligible(reason: string): boolean;

package/dist/ops/ops-engine.js

@@ -159,6 +159,25 @@ export function isNoEffectiveChangeError(reason) {
     //   "No effective meta change for…"          /  "Edit plan produced no changes"
     return /no effective \w+ change/i.test(reason) || /produced no changes/i.test(reason);
 }
+/**
+ * Within a no-effective-change, did the stored values already match?
+ *
+ * The engine throws two different things and they are not the same fact:
+ *
+ *   "No effective prop change across plan. All update patches matched
+ *    existing values."   → the content really was already what was asked for
+ *   "Edit plan produced no changes"
+ *                        → the plan had nothing left to apply, which is what
+ *                          happens when every prop in it was stripped as
+ *                          unsupported by the block
+ *
+ * Reporting the second as the first tells the author their content is up to
+ * date when their request was in fact dropped. Both messages are pinned by
+ * `isNoEffectiveChangeError` above, so they are already load-bearing strings.
+ */
+export function isAlreadyCurrentError(reason) {
+    return /no effective \w+ change/i.test(reason);
+}
 export function classifyGuardrailError(reason) {
     const lower = reason.toLowerCase();
     if (isNoEffectiveChangeError(reason))
@@ -404,7 +423,7 @@ function _resolveBlockIndex(blocks, blockId, fuzzyMatches) {
  * Drop an adapter's provenance keys from a block that is being copied.
  *
  * A projected block carries the adapter's answer to "which upstream thing is
- * this", and the adapter routes the write by it: Paintball Arena Bern marks a
+ * this", and the adapter routes the write by it: a field-level-i18n CMS marks a
  * block with `props._sectionId` and publishes anything carrying one into the
  * *shared section document* rather than into the page. Copied verbatim onto a
  * duplicate, the first edit to that duplicate's hero is written back into the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "0.2.3",
-    "@avocadostudio-ai/shared": "0.2.3"
+    "@avocadostudio-ai/migration-sdk": "^0.3.1",
+    "@avocadostudio-ai/shared": "^0.3.1"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",
@@ -56,7 +56,7 @@
     "visual-editing"
   ],
   "license": "Apache-2.0",
-  "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/orchestrator-core#readme",
+  "homepage": "https://docs.avocadostudio.dev",
   "bugs": {
     "url": "https://github.com/avocadostudio-ai/avocado/issues"
   },