@agent-native/core 0.169.0 → 0.170.0

package/corpus/templates/factory/server/lib/factory-config-reconcile.ts

@@ -0,0 +1,321 @@
+import { DEFAULT_FACTORY_ID } from "../factory-graph/store.js";
+import { factoryConfigRowId } from "./factory-scope.js";
+
+export type FactoryConfigSqlRow = {
+  id: string;
+  org_id: string | null;
+  factory_id: string | null;
+  slack_workspace: string | null;
+  slack_channel_id: string | null;
+  slack_channel_name: string | null;
+  builder_slack_user_id: string | null;
+  polling_enabled: number | null;
+  last_slack_ts: string | null;
+  slack_history_cursor: string | null;
+  repository: string | null;
+  github_polling_enabled: number | null;
+  sentry_polling_enabled: number | null;
+  sentry_org_slug: string | null;
+  sentry_project_slug: string | null;
+  sentry_environment: string | null;
+  last_sentry_seen_at: string | null;
+  automation_failure_alerts_enabled: number | null;
+  automation_failure_alert_email: string | null;
+  last_automation_failure_alert_key: string | null;
+  last_automation_failure_alert_at: string | null;
+  owner_email: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+};
+
+export type FactoryConfigReconcilePlan = {
+  fromId: string;
+  row: FactoryConfigSqlRow;
+  deleteIds: string[];
+};
+
+function rowText(row: Record<string, unknown>, key: string): string | null {
+  return asText(row[key]);
+}
+
+function rowFlag(row: Record<string, unknown>, key: string): number | null {
+  const value = row[key];
+  if (value === null || value === undefined || value === "") return null;
+  return Number(value) === 1 ? 1 : 0;
+}
+
+export function factoryConfigSqlRowFromQuery(
+  row: Record<string, unknown>,
+): FactoryConfigSqlRow | null {
+  const id = rowText(row, "id");
+  if (!id) return null;
+  return {
+    id,
+    org_id: rowText(row, "org_id"),
+    factory_id: rowText(row, "factory_id"),
+    slack_workspace: rowText(row, "slack_workspace"),
+    slack_channel_id: rowText(row, "slack_channel_id"),
+    slack_channel_name: rowText(row, "slack_channel_name"),
+    builder_slack_user_id: rowText(row, "builder_slack_user_id"),
+    polling_enabled: rowFlag(row, "polling_enabled"),
+    last_slack_ts: rowText(row, "last_slack_ts"),
+    slack_history_cursor: rowText(row, "slack_history_cursor"),
+    repository: rowText(row, "repository"),
+    github_polling_enabled: rowFlag(row, "github_polling_enabled"),
+    sentry_polling_enabled: rowFlag(row, "sentry_polling_enabled"),
+    sentry_org_slug: rowText(row, "sentry_org_slug"),
+    sentry_project_slug: rowText(row, "sentry_project_slug"),
+    sentry_environment: rowText(row, "sentry_environment"),
+    last_sentry_seen_at: rowText(row, "last_sentry_seen_at"),
+    automation_failure_alerts_enabled: rowFlag(
+      row,
+      "automation_failure_alerts_enabled",
+    ),
+    automation_failure_alert_email: rowText(
+      row,
+      "automation_failure_alert_email",
+    ),
+    last_automation_failure_alert_key: rowText(
+      row,
+      "last_automation_failure_alert_key",
+    ),
+    last_automation_failure_alert_at: rowText(
+      row,
+      "last_automation_failure_alert_at",
+    ),
+    owner_email: rowText(row, "owner_email"),
+    created_at: rowText(row, "created_at"),
+    updated_at: rowText(row, "updated_at"),
+  };
+}
+
+function asText(value: unknown): string | null {
+  if (typeof value === "string") {
+    const text = value.trim();
+    return text.length > 0 ? text : null;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return null;
+}
+
+function asFlag(value: unknown): number {
+  return Number(value) === 1 ? 1 : 0;
+}
+
+function pickText(
+  keep: string | null | undefined,
+  other: string | null | undefined,
+): string | null {
+  return asText(keep) ?? asText(other);
+}
+
+function pickLater(
+  keep: string | null | undefined,
+  other: string | null | undefined,
+): string | null {
+  const left = asText(keep);
+  const right = asText(other);
+  if (!left) return right;
+  if (!right) return left;
+  const leftNum = Number(left);
+  const rightNum = Number(right);
+  if (Number.isFinite(leftNum) && Number.isFinite(rightNum)) {
+    return leftNum >= rightNum ? left : right;
+  }
+  return left >= right ? left : right;
+}
+
+export function isUniqueConstraintError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /unique constraint failed|duplicate key|primary key/i.test(message);
+}
+
+export function mergeFactoryConfigRows(
+  keep: FactoryConfigSqlRow,
+  other: FactoryConfigSqlRow,
+): FactoryConfigSqlRow {
+  const slackIdentity = mergeSlackIdentity(keep, other);
+  return {
+    ...keep,
+    slack_workspace: slackIdentity.slack_workspace,
+    slack_channel_id: slackIdentity.slack_channel_id,
+    slack_channel_name: slackIdentity.slack_channel_name,
+    builder_slack_user_id: pickText(
+      keep.builder_slack_user_id,
+      other.builder_slack_user_id,
+    ),
+    polling_enabled: Math.max(
+      asFlag(keep.polling_enabled),
+      asFlag(other.polling_enabled),
+    ),
+    last_slack_ts: slackIdentity.last_slack_ts,
+    slack_history_cursor: slackIdentity.slack_history_cursor,
+    repository: pickText(keep.repository, other.repository),
+    github_polling_enabled: Math.max(
+      asFlag(keep.github_polling_enabled),
+      asFlag(other.github_polling_enabled),
+    ),
+    sentry_polling_enabled: Math.max(
+      asFlag(keep.sentry_polling_enabled),
+      asFlag(other.sentry_polling_enabled),
+    ),
+    sentry_org_slug: pickText(keep.sentry_org_slug, other.sentry_org_slug),
+    sentry_project_slug: pickText(
+      keep.sentry_project_slug,
+      other.sentry_project_slug,
+    ),
+    sentry_environment: pickText(
+      keep.sentry_environment,
+      other.sentry_environment,
+    ),
+    last_sentry_seen_at: pickLater(
+      keep.last_sentry_seen_at,
+      other.last_sentry_seen_at,
+    ),
+    automation_failure_alerts_enabled: Math.max(
+      asFlag(keep.automation_failure_alerts_enabled),
+      asFlag(other.automation_failure_alerts_enabled),
+    ),
+    automation_failure_alert_email: pickText(
+      keep.automation_failure_alert_email,
+      other.automation_failure_alert_email,
+    ),
+    last_automation_failure_alert_key: pickText(
+      keep.last_automation_failure_alert_key,
+      other.last_automation_failure_alert_key,
+    ),
+    last_automation_failure_alert_at: pickLater(
+      keep.last_automation_failure_alert_at,
+      other.last_automation_failure_alert_at,
+    ),
+    owner_email: pickText(keep.owner_email, other.owner_email),
+    created_at: pickText(keep.created_at, other.created_at) ?? keep.created_at,
+    updated_at: pickLater(keep.updated_at, other.updated_at),
+    org_id: keep.org_id || other.org_id,
+  };
+}
+
+export function planDefaultFactoryConfigReconciliation(
+  rows: FactoryConfigSqlRow[],
+  defaultFactoryId = DEFAULT_FACTORY_ID,
+): FactoryConfigReconcilePlan[] {
+  const byOrg = new Map<string, FactoryConfigSqlRow[]>();
+  for (const row of rows) {
+    const orgId = asText(row.org_id);
+    const id = asText(row.id);
+    if (!orgId || !id) continue;
+    const group = byOrg.get(orgId) ?? [];
+    group.push({ ...row, id, org_id: orgId });
+    byOrg.set(orgId, group);
+  }
+
+  const plans: FactoryConfigReconcilePlan[] = [];
+  for (const [orgId, group] of byOrg) {
+    const canonicalId = factoryConfigRowId(orgId, defaultFactoryId);
+    const keepSource = group.find((row) => row.id === canonicalId) ?? group[0]!;
+    let merged: FactoryConfigSqlRow = {
+      ...keepSource,
+      id: canonicalId,
+      org_id: orgId,
+      factory_id: defaultFactoryId,
+    };
+    const deleteIds: string[] = [];
+    for (const row of group) {
+      if (row.id === keepSource.id) continue;
+      merged = mergeFactoryConfigRows(merged, row);
+      deleteIds.push(row.id);
+    }
+    plans.push({
+      fromId: keepSource.id,
+      row: merged,
+      deleteIds,
+    });
+  }
+  return plans;
+}
+
+export type SlackChannelConflictClear = {
+  id: string;
+  org_id: string;
+};
+
+function mergeSlackIdentity(
+  keep: FactoryConfigSqlRow,
+  other: FactoryConfigSqlRow,
+): Pick<
+  FactoryConfigSqlRow,
+  | "slack_workspace"
+  | "slack_channel_id"
+  | "slack_channel_name"
+  | "last_slack_ts"
+  | "slack_history_cursor"
+> {
+  const keepChannel = asText(keep.slack_channel_id);
+  const otherChannel = asText(other.slack_channel_id);
+  if (!otherChannel || keepChannel === otherChannel) {
+    return {
+      slack_workspace: pickText(keep.slack_workspace, other.slack_workspace),
+      slack_channel_id: keepChannel ?? otherChannel,
+      slack_channel_name: pickText(
+        keep.slack_channel_name,
+        other.slack_channel_name,
+      ),
+      last_slack_ts: pickLater(keep.last_slack_ts, other.last_slack_ts),
+      slack_history_cursor: pickText(
+        keep.slack_history_cursor,
+        other.slack_history_cursor,
+      ),
+    };
+  }
+  if (!keepChannel) {
+    return {
+      slack_workspace: other.slack_workspace,
+      slack_channel_id: other.slack_channel_id,
+      slack_channel_name: other.slack_channel_name,
+      last_slack_ts: other.last_slack_ts,
+      slack_history_cursor: other.slack_history_cursor,
+    };
+  }
+  return {
+    slack_workspace: keep.slack_workspace,
+    slack_channel_id: keep.slack_channel_id,
+    slack_channel_name: keep.slack_channel_name,
+    last_slack_ts: keep.last_slack_ts,
+    slack_history_cursor: keep.slack_history_cursor,
+  };
+}
+
+export function planSlackChannelConflictClears(
+  rows: FactoryConfigSqlRow[],
+): SlackChannelConflictClear[] {
+  const groups = new Map<string, FactoryConfigSqlRow[]>();
+  for (const row of rows) {
+    const orgId = asText(row.org_id);
+    const channelId = asText(row.slack_channel_id);
+    const id = asText(row.id);
+    if (!orgId || !channelId || !id) continue;
+    const key = `${orgId}\0${channelId}`;
+    const group = groups.get(key) ?? [];
+    group.push({ ...row, id, org_id: orgId });
+    groups.set(key, group);
+  }
+
+  const clears: SlackChannelConflictClear[] = [];
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const ranked = [...group].sort((left, right) => {
+      const polling =
+        asFlag(right.polling_enabled) - asFlag(left.polling_enabled);
+      if (polling !== 0) return polling;
+      const updated = (right.updated_at ?? "").localeCompare(
+        left.updated_at ?? "",
+      );
+      if (updated !== 0) return updated;
+      return left.id.localeCompare(right.id);
+    });
+    for (const row of ranked.slice(1)) {
+      clears.push({ id: row.id, org_id: row.org_id! });
+    }
+  }
+  return clears;
+}

package/corpus/templates/factory/server/lib/factory-scope.ts

@@ -23,6 +23,14 @@ export const factoryIdSchema = z
   .max(120)
   .regex(/^[a-z0-9][a-z0-9-]*$/);
 
+export const builderSlackUserIdSchema = z
+  .string()
+  .trim()
+  .max(32)
+  .refine((value) => value === "" || /^[UW][A-Z0-9]+$/i.test(value), {
+    message: "Builder Slack member id must look like U01234567.",
+  });
+
 export function factoryConfigRowId(orgId: string, factoryId: string): string {
   return `${orgId}:${factoryId}`;
 }
@@ -222,7 +230,13 @@ function readFrontmatterFactoryId(content: string): string | undefined {
   return value.replace(/^(\"|')|((\"|')$)/g, "");
 }
 
-export function readAutomationFactoryId(meta: object, content: string): string {
+export function readAutomationFactoryId(
+  meta: object,
+  content: string,
+  path: string,
+): string {
+  const fromPath = readFactoryIdFromAutomationPath(path);
+  if (fromPath) return fromPath;
   const fromContent = readFrontmatterFactoryId(content);
   return resolveAutomationFactoryId(
     fromContent ? { ...meta, factoryId: fromContent } : meta,
@@ -247,6 +261,15 @@ export function isLegacyFactoryAutomationPath(path: string): boolean {
   return /^jobs\/factory-[^/]+\.md$/.test(path);
 }
 
+/** Scheduler trigger names keep the nested path; role allowlists use the leaf. */
+export function factoryAutomationLeafName(nameOrPath: string): string {
+  const withoutJobsPrefix = nameOrPath
+    .replace(/^jobs\//, "")
+    .replace(/\.md$/, "");
+  const slash = withoutJobsPrefix.lastIndexOf("/");
+  return slash === -1 ? withoutJobsPrefix : withoutJobsPrefix.slice(slash + 1);
+}
+
 export function readFactoryIdFromAutomationPath(path: string): string | null {
   const match = path.match(/^jobs\/factories\/([^/]+)\/factory-[^/]+\.md$/);
   return match?.[1] ?? null;
@@ -294,7 +317,7 @@ export async function assertUniqueSlackChannelForFactory(
           eq(triageConfig.slackChannelId, normalized),
         ),
       )
-  ).find((row) => row.factoryId && row.factoryId !== factoryId);
+  ).find((row) => row.factoryId !== factoryId);
   if (conflict) {
     throw new Error(
       "That Slack channel is already used by another Factory in this workspace.",

package/corpus/templates/factory/server/lib/require-factory-automation.ts

@@ -1,7 +1,10 @@
 import type { ActionRunContext } from "@agent-native/core/action";
 import { listAutomationDefinitions } from "@agent-native/core/triggers";
 
-import { readAutomationFactoryId } from "./factory-scope.js";
+import {
+  factoryAutomationLeafName,
+  readAutomationFactoryId,
+} from "./factory-scope.js";
 import type { WorkspaceMemberIdentity } from "./require-workspace-member.js";
 
 const FACTORY_AUTOMATION_NAMES = {
@@ -39,7 +42,10 @@ export async function requireFactoryAutomation(
   }
   const lineage = context.automation;
   const expectedNames = FACTORY_AUTOMATION_NAMES[role];
-  if (!lineage || !expectedNames.has(lineage.triggerName)) {
+  if (
+    !lineage ||
+    !expectedNames.has(factoryAutomationLeafName(lineage.triggerName))
+  ) {
     throw new Error(
       "The action was not invoked by a governed Factory automation.",
     );
@@ -71,8 +77,11 @@ export async function requireFactoryAutomation(
   }
   if (
     expectedFactoryId &&
-    readAutomationFactoryId(definition.meta, definition.resource.content) !==
-      expectedFactoryId
+    readAutomationFactoryId(
+      definition.meta,
+      definition.resource.content,
+      definition.resource.path,
+    ) !== expectedFactoryId
   ) {
     throw new Error(
       "The action was not invoked by a governed Factory automation.",

package/corpus/templates/factory/server/plugins/factory-migrations.ts

@@ -1,6 +1,128 @@
-import { runMigrations } from "@agent-native/core/db";
+import { runMigrations, type DbExec } from "@agent-native/core/db";
 import { defineNitroPlugin } from "@agent-native/core/server";
 
+import {
+  factoryConfigSqlRowFromQuery,
+  isUniqueConstraintError,
+  planDefaultFactoryConfigReconciliation,
+  planSlackChannelConflictClears,
+  type FactoryConfigSqlRow,
+} from "../lib/factory-config-reconcile.js";
+
+async function writeReconciledFactoryConfig(
+  exec: DbExec,
+  plan: {
+    fromId: string;
+    row: FactoryConfigSqlRow;
+    deleteIds: string[];
+  },
+): Promise<void> {
+  const { row } = plan;
+  await exec.execute({
+    sql: `UPDATE factory_config SET
+      id = ?,
+      factory_id = ?,
+      slack_workspace = ?,
+      slack_channel_id = ?,
+      slack_channel_name = ?,
+      builder_slack_user_id = ?,
+      polling_enabled = ?,
+      last_slack_ts = ?,
+      slack_history_cursor = ?,
+      repository = ?,
+      github_polling_enabled = ?,
+      sentry_polling_enabled = ?,
+      sentry_org_slug = ?,
+      sentry_project_slug = ?,
+      sentry_environment = ?,
+      last_sentry_seen_at = ?,
+      automation_failure_alerts_enabled = ?,
+      automation_failure_alert_email = ?,
+      last_automation_failure_alert_key = ?,
+      last_automation_failure_alert_at = ?,
+      owner_email = ?,
+      created_at = ?,
+      updated_at = ?
+      WHERE id = ? AND org_id = ?`,
+    args: [
+      row.id,
+      row.factory_id,
+      row.slack_workspace ?? "primary",
+      row.slack_channel_id,
+      row.slack_channel_name,
+      row.builder_slack_user_id,
+      row.polling_enabled ?? 0,
+      row.last_slack_ts,
+      row.slack_history_cursor,
+      row.repository,
+      row.github_polling_enabled ?? 0,
+      row.sentry_polling_enabled ?? 0,
+      row.sentry_org_slug,
+      row.sentry_project_slug,
+      row.sentry_environment,
+      row.last_sentry_seen_at,
+      row.automation_failure_alerts_enabled ?? 1,
+      row.automation_failure_alert_email,
+      row.last_automation_failure_alert_key,
+      row.last_automation_failure_alert_at,
+      row.owner_email ?? "",
+      row.created_at ?? new Date().toISOString(),
+      row.updated_at ?? new Date().toISOString(),
+      plan.fromId,
+      row.org_id,
+    ],
+  });
+  for (const deleteId of plan.deleteIds) {
+    await exec.execute({
+      sql: `DELETE FROM factory_config WHERE id = ? AND org_id = ?`,
+      args: [deleteId, row.org_id],
+    });
+  }
+}
+
+async function reconcileDefaultFactoryConfigRows(): Promise<void> {
+  const { getDbExec } = await import("@agent-native/core/db");
+  const exec = getDbExec();
+  const defaultFactoryId = "product-feedback";
+  const configRows = await exec.execute({
+    sql: `SELECT * FROM factory_config
+          WHERE factory_id IS NULL OR factory_id = '' OR factory_id = ?`,
+    args: [defaultFactoryId],
+  });
+  const rows = (configRows.rows ?? [])
+    .map((row) => factoryConfigSqlRowFromQuery(row as Record<string, unknown>))
+    .filter((row): row is FactoryConfigSqlRow => row !== null);
+  for (const plan of planDefaultFactoryConfigReconciliation(
+    rows,
+    defaultFactoryId,
+  )) {
+    await writeReconciledFactoryConfig(exec, plan);
+  }
+}
+
+async function clearDuplicateSlackChannelAssignments(): Promise<void> {
+  const { getDbExec } = await import("@agent-native/core/db");
+  const exec = getDbExec();
+  const configRows = await exec.execute({
+    sql: `SELECT * FROM factory_config`,
+    args: [],
+  });
+  const rows = (configRows.rows ?? [])
+    .map((row) => factoryConfigSqlRowFromQuery(row as Record<string, unknown>))
+    .filter((row): row is FactoryConfigSqlRow => row !== null);
+  for (const clear of planSlackChannelConflictClears(rows)) {
+    await exec.execute({
+      sql: `UPDATE factory_config SET
+        slack_channel_id = NULL,
+        slack_channel_name = NULL,
+        last_slack_ts = NULL,
+        slack_history_cursor = NULL
+        WHERE id = ? AND org_id = ?`,
+      args: [clear.id, clear.org_id],
+    });
+  }
+}
+
 const migrations = [
   {
     version: 1,
@@ -339,10 +461,20 @@ const migrations = [
         const id = String(row.id ?? "");
         if (!orgId || id.includes(":")) continue;
         const nextId = `${orgId}:${defaultFactoryId}`;
-        await exec.execute({
-          sql: `UPDATE factory_config SET id = ? WHERE id = ? AND org_id = ?`,
-          args: [nextId, id, orgId],
+        const existing = await exec.execute({
+          sql: `SELECT id FROM factory_config WHERE id = ? AND org_id = ?`,
+          args: [nextId, orgId],
         });
+        if ((existing.rows?.length ?? 0) > 0) continue;
+        try {
+          await exec.execute({
+            sql: `UPDATE factory_config SET id = ? WHERE id = ? AND org_id = ?`,
+            args: [nextId, id, orgId],
+          });
+        } catch (error) {
+          if (isUniqueConstraintError(error)) continue;
+          throw error;
+        }
       }
     },
   },
@@ -368,12 +500,24 @@ const migrations = [
   {
     version: 24,
     name: "factory-config-org-slack-channel-unique",
+    run: async () => {
+      await reconcileDefaultFactoryConfigRows();
+      await clearDuplicateSlackChannelAssignments();
+    },
     sql: `
       CREATE UNIQUE INDEX IF NOT EXISTS factory_config_org_slack_channel_idx
         ON factory_config (org_id, slack_channel_id)
         WHERE slack_channel_id IS NOT NULL AND slack_channel_id != '';
     `,
   },
+  {
+    version: 25,
+    name: "factory-config-reconcile-legacy-rows",
+    sql: {},
+    run: async () => {
+      await reconcileDefaultFactoryConfigRows();
+    },
+  },
 ];
 
 export const runFactoryMigrations = runMigrations(migrations, {

package/corpus/templates/factory/server/plugins/factory-scheduler-job.ts

@@ -39,8 +39,6 @@ import {
 } from "../triage/review-skill-alignment.js";
 
 const LEGACY_JOB_PATH = "jobs/factory-observation-scheduler.md";
-const DEFAULT_SLACK_CHANNEL_ID = "C0ATH3CCZT4";
-const DEFAULT_SLACK_CHANNEL_NAME = "product-agent-native-feedback";
 const FAILURE_ALERT_COOLDOWN_MS = 15 * 60_000;
 
 type AutomationRunFinishedEvent = {
@@ -627,6 +625,7 @@ export async function syncFactoryAutomationEnabledStates(
           readAutomationFactoryId(
             definition.meta,
             definition.resource.content,
+            definition.resource.path,
           ) === factoryId,
       )
       .map(async (definition) => {
@@ -687,16 +686,15 @@ async function ensureDefaultTriageConfig(
   }
   const now = new Date().toISOString();
   const repository = defaultRepository();
-  const pollingEnabled = 1;
   const githubPollingEnabled = defaultGithubPollingEnabled() ? 1 : 0;
   await db.insert(triageConfig).values({
     id: factoryConfigRowId(orgId, factoryId),
     factoryId,
     slackWorkspace: "primary",
-    slackChannelId: DEFAULT_SLACK_CHANNEL_ID,
-    slackChannelName: DEFAULT_SLACK_CHANNEL_NAME,
+    slackChannelId: null,
+    slackChannelName: null,
     builderSlackUserId: null,
-    pollingEnabled,
+    pollingEnabled: 0,
     githubPollingEnabled,
     sentryPollingEnabled: 0,
     lastSlackTs: null,

package/corpus/templates/factory/vitest.config.ts

@@ -1,9 +1,24 @@
 import baseConfig from "@agent-native/core/vitest-config";
-import { mergeConfig } from "vitest/config";
+import { defineConfig, mergeConfig } from "vitest/config";
 
 import viteConfig from "./vite.config";
 
 // Kept separate from vite.config.ts so the production config never imports
 // vitest: `agent-native build` loads vite.config.ts in installs where vitest
 // is absent.
-export default mergeConfig(viteConfig, baseConfig);
+export default mergeConfig(
+  viteConfig,
+  mergeConfig(
+    baseConfig,
+    defineConfig({
+      test: {
+        exclude: [
+          "**/node_modules/**",
+          "**/.git/**",
+          "**/dist/**",
+          "**/.react-router/**",
+        ],
+      },
+    }),
+  ),
+);

package/corpus/templates/forms/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/corpus/templates/forms/app/routes/_app.settings.tsx

@@ -22,7 +22,10 @@ export function meta() {
 
 export default function SettingsRoute() {
   const t = useT();
-  const agentSettingsTabs = useAgentSettingsTabs();
+  // /extensions redirects here and the agent's own navigate instructions list
+  // "extensions" as a workspace view, so the settings tab must exist too —
+  // otherwise /settings/extensions silently falls back to General.
+  const agentSettingsTabs = useAgentSettingsTabs({ extensionTools: true });
   useSetPageTitle(t("settings.title"));
 
   const generalSearchEntries = useMemo<SettingsSearchEntry[]>(

package/corpus/templates/forms/changelog/2026-08-22-the-extensions-link-now-opens-the-extensions-tab-instead-o.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-22
+---
+
+The Extensions link now opens the Extensions tab in Settings instead of silently landing on General.