Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

fix(onboarding): stop surfacing SEO agent in projects that never created one

Yuting Zhonga8b929344dae
diff --git a/src/server/actions/projects.test.ts b/src/server/actions/projects.test.ts
index d4228485..8b66a6a4 100644
--- a/src/server/actions/projects.test.ts
+++ b/src/server/actions/projects.test.ts
@@ -49,6 +49,10 @@ vi.mock("@/server/active-project", () => ({
const ensureProjectAgentsMock = vi.fn();
vi.mock("@/server/agent-templates", () => ({
ensureProjectAgents: (...args: unknown[]) => ensureProjectAgentsMock(...args),
+ // The onboarding scope constant. createProjectAction +
+ // createProjectForOnboardingAction read it from agent-templates; the
+ // reprovisionAgentsAction also passes it explicitly.
+ DEFAULT_ONBOARDING_TEMPLATE_KEYS: ["cmo", "google_ads"],
}));
const startProvisioningMock = vi.fn();
diff --git a/src/server/actions/projects.ts b/src/server/actions/projects.ts
index be47f0c8..7ba61554 100644
--- a/src/server/actions/projects.ts
+++ b/src/server/actions/projects.ts
@@ -16,7 +16,10 @@ import {
clearActiveProject,
setActiveProject,
} from "@/server/active-project";
-import { ensureProjectAgents } from "@/server/agent-templates";
+import {
+ DEFAULT_ONBOARDING_TEMPLATE_KEYS,
+ ensureProjectAgents,
+} from "@/server/agent-templates";
import { startProvisioning } from "@/server/onboarding/provisioning-state";
import { listProjectAgents, readAgentMeta } from "@/server/agent-meta";
import { cascadeDeleteAgent, relocateAgent } from "@/server/actions/agents";
@@ -47,11 +50,14 @@ export async function createProjectAction(formData: FormData): Promise<void> {
// Per D6: provision CMO + Google Ads asynchronously so the form returns
// immediately. The audit step (after OAuth) gates on completion via
// `awaitProvisioning` from server/onboarding/provisioning-state.
- // Per D4: scope to CMO + Google Ads only; SEO is opt-in later.
- const provisionPromise = ensureProjectAgents(result.project.slug, [
- "cmo",
- "google_ads",
- ]);
+ // Per D4: scope to the default onboarding bundle (SEO is opt-in later).
+ // DEFAULT_ONBOARDING_TEMPLATE_KEYS is the single source of truth — also
+ // consulted by listProjectAgents to decide which template placeholders
+ // appear in the sidebar before disk writes finish.
+ const provisionPromise = ensureProjectAgents(
+ result.project.slug,
+ DEFAULT_ONBOARDING_TEMPLATE_KEYS,
+ );
startProvisioning(result.project.slug, provisionPromise);
// Log on completion (best-effort, doesn't block form return).
provisionPromise
@@ -96,10 +102,10 @@ export async function createProjectForOnboardingAction(
if (!result.ok) return { ok: false, error: result.reason };
// Same async-provisioning policy as createProjectAction (D4 + D6).
- const provisionPromise = ensureProjectAgents(result.project.slug, [
- "cmo",
- "google_ads",
- ]);
+ const provisionPromise = ensureProjectAgents(
+ result.project.slug,
+ DEFAULT_ONBOARDING_TEMPLATE_KEYS,
+ );
startProvisioning(result.project.slug, provisionPromise);
// After provisioning resolves, mint + start the CMO's project-onboarding
// task. We chain off provisionPromise (not Promise.all) so a failed
@@ -170,7 +176,13 @@ export async function createProjectForOnboardingAction(
export async function reprovisionAgentsAction(slug: string): Promise<{ ok: true; created: string[]; existed: string[] } | { ok: false; error: string }> {
try {
- const result = await ensureProjectAgents(slug);
+ // Scope to the same set onboarding uses — clicking "Reprovision" should
+ // restore the onboarded bundle (cmo + google-ads), not auto-create
+ // opt-in templates like SEO that the user never asked for.
+ const { DEFAULT_ONBOARDING_TEMPLATE_KEYS } = await import(
+ "@/server/agent-templates"
+ );
+ const result = await ensureProjectAgents(slug, DEFAULT_ONBOARDING_TEMPLATE_KEYS);
revalidatePath("/", "layout");
return { ok: true, ...result };
} catch (err) {
diff --git a/src/server/agent-meta.test.ts b/src/server/agent-meta.test.ts
index 57fe7ec9..f8d8517c 100644
--- a/src/server/agent-meta.test.ts
+++ b/src/server/agent-meta.test.ts
@@ -75,16 +75,20 @@ vi.mock("./agent-templates", () => ({
key: "cmo",
display_name: "CMO",
description: "Chief Marketing Officer.",
+ default_onboarding: true,
},
{
key: "google_ads",
display_name: "Google Ads",
description: "Google Ads specialist.",
+ default_onboarding: true,
},
{
key: "seo",
display_name: "SEO",
description: "SEO specialist.",
+ // Opt-in template: not pre-seeded, only appears via meta sidecar.
+ default_onboarding: false,
},
],
agentNameFor: (slug: string, key: string) =>
@@ -186,28 +190,45 @@ describe("writeAgentMeta + readAgentMeta", () => {
});
describe("listProjectAgents", () => {
- it("returns templates-only when agents dir is missing", async () => {
+ it("returns the onboarding-default templates only when agents dir is missing", async () => {
fsState.missingDirs.add("/data/agents");
const r = await listProjectAgents("acme");
- expect(r).toHaveLength(3);
+ // SEO is template_key: 'seo' with default_onboarding: false — it should
+ // NOT appear until something explicitly provisions it for the project.
+ expect(r).toHaveLength(2);
expect(r.map((e) => e.agent_id)).toEqual([
"acme-cmo",
"acme-google-ads",
- "acme-seo",
]);
expect(r.every((e) => e.is_template_default)).toBe(true);
});
- it("returns templates-only when agents dir exists but has no entries for the project", async () => {
+ it("returns onboarding-default templates only when agents dir exists but has no entries for the project", async () => {
// Empty dir: readdir resolves to [], no entries match.
const r = await listProjectAgents("acme");
expect(r.map((e) => e.agent_id)).toEqual([
"acme-cmo",
"acme-google-ads",
- "acme-seo",
]);
});
+ it("includes an opt-in template (e.g. SEO) once a meta sidecar is written for it", async () => {
+ await writeAgentMeta(
+ makeMeta({
+ agent_id: "acme-seo",
+ slug: "seo",
+ display_name: "SEO",
+ template_key: "seo",
+ }),
+ );
+ const r = await listProjectAgents("acme");
+ const seo = r.find((e) => e.agent_id === "acme-seo");
+ expect(seo).toBeDefined();
+ expect(seo?.template_key).toBe("seo");
+ // It now appears as a non-template-default entry (overlay row wins).
+ expect(seo?.is_template_default).toBe(false);
+ });
+
it("overlays a meta sidecar so is_template_default flips to false", async () => {
await writeAgentMeta(makeMeta()); // /data/agents/acme-cmo/notfair-meta.json
const r = await listProjectAgents("acme");
@@ -255,11 +276,11 @@ describe("listProjectAgents", () => {
}),
);
const r = await listProjectAgents("acme");
- // Templates first in declared order, then custom alphabetically by slug.
+ // Onboarding-default templates first in declared order (SEO is opt-in
+ // and not seeded), then custom alphabetically by slug.
expect(r.map((e) => e.slug)).toEqual([
"cmo",
"google-ads",
- "seo",
"a-tool",
"z-tool",
]);
@@ -276,8 +297,8 @@ describe("listProjectAgents", () => {
);
const r = await listProjectAgents("acme");
expect(r.find((e) => e.agent_id === "globex-cmo")).toBeUndefined();
- // Still has the 3 templates for acme.
- expect(r.filter((e) => e.is_template_default)).toHaveLength(3);
+ // Still has the onboarding-default templates for acme.
+ expect(r.filter((e) => e.is_template_default)).toHaveLength(2);
});
it("skips entries with a matching prefix but no meta sidecar", async () => {
@@ -285,9 +306,9 @@ describe("listProjectAgents", () => {
// OpenClaw workspace dir without the sidecar (e.g., pre-sidecar agents).
fsState.dirs.add("/data/agents/acme-orphan");
const r = await listProjectAgents("acme");
- // Should not include acme-orphan; just the templates.
+ // Should not include acme-orphan; just the onboarding-default templates.
expect(r.find((e) => e.agent_id === "acme-orphan")).toBeUndefined();
- expect(r).toHaveLength(3);
+ expect(r).toHaveLength(2);
});
});
diff --git a/src/server/agent-meta.ts b/src/server/agent-meta.ts
index 1c575c03..ef9b38de 100644
--- a/src/server/agent-meta.ts
+++ b/src/server/agent-meta.ts
@@ -76,8 +76,13 @@ export type ProjectAgentEntry = {
export async function listProjectAgents(project_slug: string): Promise<ProjectAgentEntry[]> {
const result = new Map<string, ProjectAgentEntry>();
- // 1) Seed with templates (they may or may not exist on disk yet).
+ // 1) Seed with the templates an onboarded project actually has. Opt-in
+ // templates (e.g. SEO until v1.1 lights it up) live in TEMPLATES but
+ // are NOT pre-seeded — they only appear when a meta sidecar shows
+ // one was actually provisioned. This is how we keep the sidebar from
+ // pretending SEO exists when the onboarding scope is cmo+google-ads.
for (const t of TEMPLATES) {
+ if (!t.default_onboarding) continue;
const agentId = agentNameFor(project_slug, t.key);
result.set(agentId, {
agent_id: agentId,
diff --git a/src/server/agent-templates.ts b/src/server/agent-templates.ts
index 3fd5ab2b..66029278 100644
--- a/src/server/agent-templates.ts
+++ b/src/server/agent-templates.ts
@@ -104,10 +104,27 @@ export type AgentTemplate = {
capabilities: string[];
model: string;
system_prompt: string;
+ /**
+ * True when this template is included in the default onboarding bundle
+ * (provisioned on project create + always shown in the sidebar even
+ * before disk writes finish). False = opt-in: the template exists for
+ * future use, but nothing surfaces it until something explicitly
+ * provisions a clone of it for a project.
+ */
+ default_onboarding: boolean;
};
export type AgentTemplateKey = AgentTemplate["key"];
+/**
+ * Subset of TEMPLATES included in the default onboarding bundle. Single
+ * source of truth for "which agents does a freshly-created project get?".
+ * Used by createProject actions to scope ensureProjectAgents and by
+ * listProjectAgents to decide which template entries to synthesize as
+ * placeholders before disk-overlay merges in.
+ */
+export const DEFAULT_ONBOARDING_TEMPLATE_KEYS: AgentTemplateKey[] = ["cmo", "google_ads"];
+
export function templateForKey(key: string): AgentTemplate | undefined {
return TEMPLATES.find((t) => t.key === key || t.key.replace(/_/g, "-") === key);
}
@@ -139,6 +156,7 @@ export const TEMPLATES: AgentTemplate[] = [
system_prompt: `You are the CMO for a marketing project on the notfair-cmo platform.
${CMO_ROLE}`,
+ default_onboarding: true,
},
{
key: "google_ads",
@@ -166,6 +184,7 @@ a wide net on the first pass; filter in-script for free.
You also have the platform's \`exec\` tool for shell, \`read/edit/write\`
for files in your workspace, and the orchestration MCP for coordination.`,
+ default_onboarding: true,
},
{
key: "seo",
@@ -191,6 +210,7 @@ is connected, use it for ranking + click data.
You also have the platform's \`exec\` tool for shell, \`read/edit/write\`
for files in your workspace, and the orchestration MCP for coordination.`,
+ default_onboarding: false,
},
];