@frontera-sdk/cli 1.53.23 → 1.53.25

package/src/commands/local/sync.ts

@@ -3,8 +3,8 @@ import { basename, join } from 'node:path'
 
 import { CliError, UsageError } from '../../errors'
 import { canPrompt, promptSecret } from '../../prompt'
-import { allTargets } from '../../local/local-dev-sync'
 import { pullDocuments, type DocumentsPulled } from '../../local/local-knowledge-documents'
+import { KNOWLEDGE_SIGN_IN, lockedFolders, pullKnowledgeBaseDocuments } from '../../local/local-knowledge-base-pull'
 import { appCodeLine, appCodeVersion, earlierPullShadows, pullAppCode, type AppCodePulled } from '../../local/local-app-code'
 import { remakeLines, remakeReason, remakeSampleData, type SampleRemake } from '../../local/local-sample-remake'
 import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/local-lessons'
@@ -18,6 +18,7 @@ import {
   linkTarget,
   namedTarget,
   organizationReader,
+  personReader,
   projectFile,
   projectKeyFingerprints,
   projectTargets,
@@ -93,6 +94,7 @@ import {
   usesGovernedActions,
   writeBase,
   type ClearedConflicts,
+  type FetchOptions,
   type FetchResult,
   type RemoteSnapshot,
 } from '../../local/local-sync-snapshot'
@@ -185,31 +187,29 @@ export async function sourceFor(owner: KeyOwner, link: SyncLink, name: string |
   const key = getSyncKey(owner, 'workspace')
   if (!key) throw new CliError(`no workspace key for ${name ? `target ${name}` : 'this project'} on this machine`, { code: 'SYNC_NO_KEY', hint: `run \`${targetWords({ name }, 'frontera local sync connect')}\` to store one (the link is in frontera.yaml; keys are per machine)` })
   const { client, notSteward } = await organizationReader(owner, link)
+  // After it: a profile that did not know its organization yet is recorded there once.
+  const person = await personReader(owner, link)
   return {
     workspace: syncClient(link.platform, key),
     ...(client ? { organization: client } : {}),
     workspaceId: link.workspace,
     ...(notSteward ? { notSteward } : {}),
+    ...(person ? { person } : {}),
   }
 }
 
-/** Items the project holds that the workspace may not: for the plan's "only here". */
+/**
+ * Items the project holds that the workspace may not: for the plan's "only
+ * here", as a push lists them. An Agent's lessons are counted apart.
+ */
 function localItems(project: LocalProject): Array<{ ref: string; kind: SyncKind; name: string; files: string[] }> {
-  return allTargets(project.root).flatMap((t): Array<{ ref: string; kind: SyncKind; name: string; files: string[] }> => {
-    if (t.kind === 'agent') return [{ ref: `agent/${t.slug}`, kind: 'agent', name: t.slug, files: [t.file] }]
-    if (t.kind === 'workflow') return [{ ref: `workflow/${t.slug}`, kind: 'workflow', name: t.slug, files: [t.file] }]
-    if (t.kind === 'function') {
-      const name = basename(t.file).replace(/\.ts$/, '')
-      return [{ ref: `function/${name}`, kind: 'function', name, files: [t.file] }]
-    }
-    return []
-  })
+  return [...projectRefs(project.root)].flatMap(([ref, { kind, name, file }]) => (kind === 'lessons' ? [] : [{ ref, kind, name, files: [file] }]))
 }
 
 function kindsFlag(ctx: CommandContext): Set<SyncKind> | undefined {
   const raw = flagString(ctx, 'kinds')
   if (!raw) return undefined
-  const aliases: Record<string, SyncKind> = { agents: 'agent', workflows: 'workflow', functions: 'function', skills: 'skill', plugins: 'plugin', evaluations: 'evaluation', evals: 'evaluation', datasets: 'dataset', themes: 'theme', 'chat-apps': 'chat-app', chatapps: 'chat-app', apps: 'app' }
+  const aliases: Record<string, SyncKind> = { 'knowledge-bases': 'knowledge-base', agents: 'agent', workflows: 'workflow', functions: 'function', skills: 'skill', plugins: 'plugin', evaluations: 'evaluation', evals: 'evaluation', datasets: 'dataset', themes: 'theme', 'chat-apps': 'chat-app', chatapps: 'chat-app', apps: 'app' }
   const out = new Set<SyncKind>()
   for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
     const kind = (aliases[part] ?? part) as SyncKind
@@ -261,9 +261,9 @@ export async function settleConflicts(project: LocalProject, link: SyncLink, sna
 }
 
 /** Fetch into the snapshot with the project's keys, then bring conflicted items up to the newer version. */
-export async function fetchFor(project: LocalProject, link: SyncLink, opts: { full?: boolean } = {}): Promise<FetchResult & { conflicts: ConflictsSettled }> {
+export async function fetchFor(project: LocalProject, link: SyncLink, opts: Pick<FetchOptions, 'full' | 'knowledgeBaseFolders'> = {}): Promise<FetchResult & { conflicts: ConflictsSettled }> {
   const source = await sourceFor(project, link)
-  const result = await fetchWorkspace(project.root, source, { blueprint: link.blueprint, full: opts.full })
+  const result = await fetchWorkspace(project.root, source, { blueprint: link.blueprint, full: opts.full, knowledgeBaseFolders: opts.knowledgeBaseFolders })
   await nameLink(project, link, source)
   return { ...result, conflicts: await settleConflicts(project, link, result.snapshot, source) }
 }
@@ -273,10 +273,10 @@ export async function fetchFor(project: LocalProject, link: SyncLink, opts: { fu
  * target into its own snapshot (`target.state`) with its own keys. A named
  * target is never pulled from, so it has no conflicts to settle.
  */
-export async function fetchTarget(project: LocalProject, target: SyncTarget, opts: { full?: boolean } = {}): Promise<FetchResult> {
+export async function fetchTarget(project: LocalProject, target: SyncTarget, opts: Pick<FetchOptions, 'full' | 'knowledgeBaseFolders'> = {}): Promise<FetchResult> {
   if (!target.name) return fetchFor(project, target.link, opts)
   const source = await sourceFor(target.owner, target.link, target.name)
-  const result = await fetchWorkspace(target.state, source, { blueprint: target.link.blueprint, full: opts.full })
+  const result = await fetchWorkspace(target.state, source, { blueprint: target.link.blueprint, full: opts.full, knowledgeBaseFolders: opts.knowledgeBaseFolders })
   await nameLink(project, target.link, source, (named) => writeTarget(project.root, target.name!, { ...named, ...(target.production ? { production: true } : {}) }))
   return result
 }
@@ -370,7 +370,7 @@ async function refreshLocalCatalog(project: LocalProject): Promise<void> {
   if (models?.length) rememberLocalCatalog(project.root, models)
 }
 
-export async function planFor(project: LocalProject, link: SyncLink, opts: { kinds?: Set<SyncKind>; drafts?: Set<string>; fetch?: 'auto' | 'always' | 'never'; repair?: 'offline' | 'online' } = {}) {
+export async function planFor(project: LocalProject, link: SyncLink, opts: { kinds?: Set<SyncKind>; drafts?: Set<string>; fetch?: 'auto' | 'always' | 'never'; repair?: 'offline' | 'online'; full?: boolean } = {}) {
   await refreshLocalCatalog(project)
   const local = localItems(project).filter((l) => !opts.kinds || opts.kinds.has(l.kind))
   const readFromBase = (path: string) => readBase(project.root, path)
@@ -378,14 +378,14 @@ export async function planFor(project: LocalProject, link: SyncLink, opts: { kin
   if (opts.drafts?.size) {
     const lock = readLock(project.root)
     const base = lock?.workspace === link.workspace ? lock : null
-    const remote = await readWorkspace(await sourceFor(project, link), { kinds: opts.kinds, drafts: opts.drafts, blueprint: link.blueprint })
+    const remote = await readWorkspace(await sourceFor(project, link), { kinds: opts.kinds, drafts: opts.drafts, blueprint: link.blueprint, knowledgeBaseFolders: lockedFolders(project.root) })
     return { remote, plan: computePlan(project.root, remote.items, base, local, { base: readFromBase, directory: remote.directory }), lock, snapshot: null, fetched: null, bases: noBases }
   }
   let snapshot = snapshotFor(project, link)
   let fetched: Awaited<ReturnType<typeof fetchFor>> | null = null
   const stale = !snapshot || Date.now() - Date.parse(snapshot.fetchedAt) > FRESH_MS
   if (opts.fetch === 'always' || (opts.fetch !== 'never' && stale)) {
-    fetched = await fetchFor(project, link)
+    fetched = await fetchFor(project, link, { full: opts.full })
     snapshot = fetched.snapshot
   }
   // Read after the fetch: settling conflicts may have moved it.
@@ -788,11 +788,14 @@ const pull = async (ctx: CommandContext) => {
   const byRef = new Map(remote.items.map((i) => [i.ref, i]))
   // Knowledge bases whose documents come too: every base this pull writes (a pulled Agent answers from them),
   // unless --no-documents; --documents names more, already in the project, to bring theirs again.
+  // A Knowledge app base (`knowledge-base/<folder>`) brings its documents only when named.
   const noDocuments = flagBool(ctx, 'no-documents')
-  const documents = refsFlag(ctx, 'documents').map((r) => r.replace(/^knowledge\//, ''))
-  if (noDocuments && documents.length) throw new UsageError('--documents and --no-documents ask opposite things', 'leave one out: --no-documents pulls no documents; --documents <name> pulls those bases\' documents')
-  const noBase = documents.filter((n) => !byRef.has(`knowledge/${n}`))
-  if (noBase.length) throw new UsageError(`no knowledge base ${noBase.join(', ')} in the workspace`, '--documents takes knowledge base names, as `--preview` lists them (knowledge/<name>)')
+  const asked = refsFlag(ctx, 'documents')
+  const baseDocuments = asked.filter((r) => r.startsWith('knowledge-base/'))
+  const documents = asked.filter((r) => !r.startsWith('knowledge-base/')).map((r) => r.replace(/^knowledge\//, ''))
+  if (noDocuments && asked.length) throw new UsageError('--documents and --no-documents ask opposite things', 'leave one out: --no-documents pulls no documents; --documents <name> pulls those bases\' documents')
+  const noBase = [...documents.filter((n) => !byRef.has(`knowledge/${n}`)), ...baseDocuments.filter((r) => !byRef.has(r) || r === 'knowledge-base/settings')]
+  if (noBase.length) throw new UsageError(`no knowledge base ${noBase.join(', ')} in the workspace`, '--documents takes knowledge base names, as `--preview` lists them (knowledge/<name>, or knowledge-base/<name> for the Knowledge app)')
   const byPlan = new Map(plan.map((p) => [p.ref, p]))
   const status = new Map(plan.map((p) => [p.ref, p.status]))
   const clean = (p: PlanItem) => p.status === 'changed' || (p.status === 'conflict' && p.merge?.conflicts === 0)
@@ -813,13 +816,14 @@ const pull = async (ctx: CommandContext) => {
   } else if (kinds) {
     // A kind pulls what is new, changed or merges cleanly; it never replaces local edits unasked.
     chosen = plan.filter((p) => p.status === 'new' || clean(p)).map((p) => p.ref)
-  } else if (deleteHere.length || keepLocal.length || documents.length || flagBool(ctx, 'lessons')) {
+  } else if (deleteHere.length || keepLocal.length || documents.length || baseDocuments.length || flagBool(ctx, 'lessons')) {
     chosen = []
   } else {
     throw new UsageError('say what to pull', 'name items (`agent/support-concierge`), kinds (`--kinds workflows`), or `--all-changed`; `--preview` lists them')
   }
   // A knowledge base not in the project yet comes with its documents.
   for (const n of documents) if (status.get(`knowledge/${n}`) === 'new' && !chosen.includes(`knowledge/${n}`)) chosen.push(`knowledge/${n}`)
+  for (const r of baseDocuments) if (status.get(r) === 'new' && !chosen.includes(r)) chosen.push(r)
   // An item pulled with conflicts waits for `resolve`: a pull writes nothing else for it.
   const waiting = chosen.filter((r) => status.get(r) === 'unresolved')
   chosen = chosen.filter((r) => status.get(r) !== 'unresolved')
@@ -869,6 +873,15 @@ const pull = async (ctx: CommandContext) => {
       docs[n] = id ? await pullDocuments(project.root, client, { name: n, id }) : { written: [], present: [], skipped: [], failed: ['its id is not in the fetched snapshot: fetch again'] }
     }
   }
+  if (baseDocuments.length) {
+    // Read as the person signed in: a key never reads the Knowledge app.
+    const person = await personReader(project, link)
+    for (const r of baseDocuments) {
+      const id = byRef.get(r)?.id
+      const folder = r.slice('knowledge-base/'.length)
+      docs[r] = !person ? { written: [], present: [], skipped: [], failed: [KNOWLEDGE_SIGN_IN] } : id ? await pullKnowledgeBaseDocuments(project.root, person.workspace, { folder, id }) : { written: [], present: [], skipped: [], failed: ['its id is not in the fetched snapshot: fetch again'] }
+    }
+  }
   // Each pulled Custom App's code comes too, into apps/<slug>/, unless --no-app-code; a folder already there is kept,
   // except one an earlier pull left unchanged whose package.json and bun.lock disagree: the deployed source replaces it.
   const appCode: AppCodePulled[] = []
@@ -930,7 +943,7 @@ const pull = async (ctx: CommandContext) => {
           ...lessons.removed.map((a) => `  ${a}: no reviewed rules in the workspace any more; agents/${a}/lessons.yaml removed`),
         ]
   const docLines = Object.entries(docs).flatMap(([n, d]) => [
-    `  ${n}: ${plural(d.written.length, 'document')} written${d.present.length ? `, ${d.present.length} already here` : ''}${d.skipped.length ? `, ${d.skipped.length} not a kind local dev uploads (${d.skipped.join(', ')})` : ''}`,
+    `  ${n}: ${plural(d.written.length, 'document')} written${d.present.length ? `, ${d.present.length} already here` : ''}${d.skipped.length ? `, ${d.skipped.length} ${n.startsWith('knowledge-base/') ? 'kept on the platform by their source' : 'not a kind local dev uploads'} (${d.skipped.join(', ')})` : ''}`,
     ...d.failed.map((f) => `      could not read ${f}`),
   ])
   // What won't run locally as pulled, with the reason and whose fix it is: the checks `local dev` applies.
@@ -1310,6 +1323,8 @@ export const localSync: Command = {
       'frontera local sync pull knowledge/faq',
       'frontera local sync pull --kinds knowledge --no-documents',
       'frontera local sync pull --documents faq',
+      'frontera local sync pull --kinds knowledge-bases',
+      'frontera local sync pull --documents knowledge-base/hr-policies',
       'frontera local sync pull app/ops-console --no-app-code',
       'frontera local sync pull agent/support-concierge --lessons',
       'frontera local sync diff agent/support-concierge',

package/src/commands/registry.ts

@@ -37,6 +37,7 @@ import { capabilityCommands } from './capability/index-commands'
 import { datasetCommands } from './dataset/index-commands'
 import { sourceCommands } from './source/index-commands'
 import { knowledgeCommands } from './knowledge/index-commands'
+import { knowledgeBaseCommands } from './knowledge-base/index-commands'
 import { mediaCommands } from './media/index-commands'
 import { packCommands } from './pack/index-commands'
 import { secretCommands } from './secret/index-commands'
@@ -133,6 +134,7 @@ export const COMMANDS: readonly Command[] = [
   ...datasetCommands,
   ...sourceCommands,
   ...knowledgeCommands,
+  ...knowledgeBaseCommands,
   ...mediaCommands,
   ...packCommands,
   ...secretCommands,
@@ -212,7 +214,8 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   plugin: 'Integrations and MCP servers connected to this workspace',
   dataset: 'Source datasets a Blueprint object type can bind to',
   source: 'Connected Sources — where a dataset’s rows come from',
-  knowledge: 'Knowledge bases and the sources inside them',
+  knowledge: 'Agent knowledge — the bases Agents attach, and their files',
+  'knowledge-base': 'Knowledge app bases — search, documents, stewards',
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
   voice: 'Voice — Agent phone numbers and outbound calls',

package/src/commands/types.ts

@@ -86,6 +86,12 @@ export interface CommandMeta {
    * is refused, so a noun names its way out without rewording the refusal.
    */
   sessionAlternative?: string
+  /**
+   * Session-lane only: on the project's own local runtime, with no `--as`,
+   * the command acts as the runtime's owner, whose session the runtime keeps
+   * (Studio acts as the same person). Elsewhere a person signs in as usual.
+   */
+  localOwner?: boolean
   /**
    * Present → the command is planned but unbuilt, and fails with this message.
    * Reserved in the table rather than omitted: a caller reading "unknown

package/src/flag-help.ts

@@ -101,7 +101,8 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   // Local runtime (internal FDE tooling)
   source: 'platform checkout to run the local runtime from (default: the one this CLI runs from)',
   image: 'run the local runtime from release images instead of a platform checkout',
-  exclude: 'optional components to leave out of the local runtime: jobs, runner, storage',
+  exclude: 'optional components to leave out of the local runtime: jobs, runner, storage, search-index',
+  with: 'components the local runtime runs only when asked: search-index, which a project with a knowledge-base/ folder runs anyway',
   'no-backup': 'also delete the local database and secrets',
   follow: 'keep printing new log lines as they are written',
   lines: 'how many of the latest log lines to print (default 100)',
@@ -199,8 +200,11 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   limit: 'maximum rows to return in one page; each surface has its own ceiling',
   'page-token': 'cursor from the previous response’s nextPageToken; omit for the first page',
   as:
-    'on the local runtime only: act as a local persona (`submitter`, or an approval step such as '
-    + '`dispatch_lead`), as `frontera local status` lists them; refused anywhere else',
+    'on the local runtime only: act as a local persona (`submitter`, an approval step such as '
+    + '`dispatch_lead`, or `knowledge-steward`, `workspace-member`, `outsider` for knowledge bases), '
+    + 'as `frontera local status` lists them; refused anywhere else',
+  base: 'a knowledge base by name, id or project folder',
+  'credential-from': 'where to read a credential from: `-` for stdin, or a file path. Never an inline value',
   // A metric's query (`blueprint metric query`).
   measure: 'comma-separated measures of the metric to return; all of them when absent',
   'group-by': 'comma-separated dimensions of the metric to break the numbers down by',
@@ -293,7 +297,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   title: 'the change request’s title; a push that opens a new one needs it',
   why: 'a person-step: why it is needed now, in a sentence',
   changes: 'a person-step: what it changes, in the workspace’s words',
-  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person, registry-owner)',
+  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, knowledge-steward, admin, second-person, person, registry-owner)',
   delivery: 'a person-step: the delivery it belongs to; steps with the same one show as one card',
   all: 'list the settled ones too',
   browser: 'sign in by approving a code in the browser, as yourself',
@@ -385,6 +389,8 @@ const PLACEHOLDER: Readonly<Record<string, string>> = {
   end: 'iso',
   only: 'live|test',
   as: 'persona',
+  base: 'name',
+  'credential-from': '-|path',
   cursor: 'cursor',
   lifecycle: 'state',
   actions: 'allow_all|read_only|custom',

package/src/forge/touches.ts

@@ -35,6 +35,7 @@ export const FORGE_ARTIFACT_KINDS = [
   'source',
   'dataset',
   'knowledge',
+  'knowledge-base',
   'workflow',
 ] as const satisfies readonly ForgeArtifactKind[]
 
@@ -55,6 +56,8 @@ export const TOUCHING_VERBS: Record<ForgeArtifactKind, readonly string[]> = {
   // `revise` cuts the dataset's next revision from its CSV.
   dataset: ['create', 'upload', 'revise', 'test-source'],
   knowledge: ['create', 'attach', 'detach', 'upload', 'retry', 'delete'],
+  // The Knowledge app's bases, recorded through `ACTION_VERBS`: `source sync` and `steward add|remove`.
+  'knowledge-base': ['sync', 'steward'],
   // `webhook-test` starts a run on the draft through its webhook, as `run` does.
   // `get`, `lineage`, `list`, `runs` and `validate` are reads — `validate` is
   // `push --dry-run` and writes nothing. `cancel` is deliberately absent: it
@@ -93,6 +96,20 @@ export const AGENT_PROXY_NOUNS: Record<string, { verbs: readonly string[]; agent
   voice: { verbs: ['number-add', 'number-apply', 'number-enable', 'number-disable', 'number-hours', 'number-remove'], agentAt: 0 },
 }
 
+/**
+ * Verbs whose first positional is an action, only some of which change the
+ * artifact: `knowledge-base source test` stores nothing, `source sync` makes
+ * the source due now. The action names the verb the touch records, and
+ * `refAt` the positional after the action that names the artifact (null: a
+ * steward is a person, never a ref).
+ */
+export const ACTION_VERBS: Partial<Record<ForgeArtifactKind, Record<string, { actions: Record<string, string>; refAt: number | null }>>> = {
+  'knowledge-base': {
+    source: { actions: { sync: 'sync' }, refAt: 0 },
+    steward: { actions: { add: 'steward', remove: 'steward' }, refAt: null },
+  },
+}
+
 /**
  * Verbs whose positional is a FILE, not the artifact's name. `frontera
  * function deploy src/nightly.ts` names a source file; the slug comes from
@@ -180,6 +197,9 @@ export const MCP_READ_TOOLS = new Set([
   'workflow_test_step',
 ])
 
+/** `frontera mcp`'s knowledge base tools that change nothing; they are not in the service's catalogue. */
+export const KNOWLEDGE_BASE_READ_TOOLS = new Set(['knowledge_base_list', 'knowledge_base_search', 'knowledge_base_status'])
+
 /** Tools whose success makes the artifact LIVE. */
 export const MCP_LIVE_TOOLS = new Set([
   'publish_agent', 'promote_platform_app_version', 'workflow_promote_version', 'promote_function_version',
@@ -219,6 +239,8 @@ function mcpArtifact(tool: string, input: Record<string, unknown>): { kind: Forg
   if (tool === 'data_refresh_dataset') return { kind: 'dataset', ref: str('apiName') }
   if (tool === 'promote_platform_app_version') return { kind: 'app', ref: str('app') ?? str('slug') }
   if (/_skill$/.test(tool)) return { kind: 'skill', ref: str('slug') ?? str('skillId') }
+  // The Knowledge app's bases, from `frontera mcp`, ahead of Agent knowledge, whose tools also say "knowledge".
+  if (tool.startsWith('knowledge_base_')) return KNOWLEDGE_BASE_READ_TOOLS.has(tool) ? null : { kind: 'knowledge-base', ref: str('base') }
   if (/knowledge/.test(tool)) return { kind: 'knowledge', ref: str('knowledgeBaseId') ?? str('name') }
   if (/^create_agent$|^duplicate_agent$/.test(tool)) return { kind: 'agent', ref: null }
   return null
@@ -398,6 +420,13 @@ export function parseFronteraCommands(line: string): ParsedFronteraCommand[] {
 
     const kind = NOUN_ALIASES[noun] ?? (isKind(noun) ? noun : null)
     if (!kind) continue
+    const acting = ACTION_VERBS[kind]?.[verb]
+    if (acting) {
+      const [action, ...after] = rest
+      const touch = action ? acting.actions[action] : undefined
+      if (touch) out.push({ kind, verb: touch, ref: acting.refAt === null ? null : (after[acting.refAt] ?? null), live: false })
+      continue
+    }
     if (!TOUCHING_VERBS[kind].includes(verb)) continue
     const ref = (FILE_POSITIONAL_VERBS[kind] ?? []).includes(verb)
       ? null

package/src/local/local-applied.ts

@@ -8,6 +8,8 @@ import type { LocalProject } from './local-project'
 import { standInTools } from './local-stand-ins'
 import { importedFiles } from './local-function-shared'
 import { NOT_A_DIFFERENCE_HERE } from './local-org-settings'
+import { KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_SETTINGS_FILE } from './local-knowledge-base-files'
+import { agentPicks, appliedBaseIds, pickedFolder } from './local-knowledge-base-apply'
 
 /**
  * What `frontera local dev` has applied to this runtime, by content hash. It
@@ -71,11 +73,25 @@ function treeHash(dir: string): string | null {
   return any ? hash.digest('hex') : null
 }
 
+/** An agent.json's `knowledgeBases`, or null when it has none or cannot be read. */
+function agentPicksIn(path: string): string[] | null {
+  try {
+    return agentPicks(JSON.parse(readFileSync(path, 'utf8')))
+  } catch {
+    return null
+  }
+}
+
 export function contentHash(project: LocalProject, target: SyncTarget): string | null {
   // The Blueprint is applied as one tree, so it changes when any file in it does.
   if (target.kind === 'blueprint') return treeHash(join(project.root, 'blueprint'))
   // A knowledge base, a skill and a slide theme are folders: a new document, reference or image changes them.
   if (target.kind === 'knowledge' || target.kind === 'skill' || target.kind === 'theme' || target.kind === 'brand') return treeHash(join(project.root, dirname(target.file)))
+  // A Knowledge app base, and the settings that allow its sources: allowing them applies it again.
+  if (target.kind === 'knowledge-base') {
+    const tree = treeHash(join(project.root, dirname(target.file)))
+    return tree && createHash('sha256').update(tree).update(fileDigest(join(project.root, KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_SETTINGS_FILE)) ?? '').digest('hex')
+  }
   // A stand-in lists the connection's tools and those the project's files name on it: either changing re-applies it.
   if (target.kind === 'plugin' && target.file.endsWith('.stand-in.json')) return createHash('sha256').update(JSON.stringify(standInTools(project.root, target.name))).update(fileDigest(join(project.root, target.file)) ?? '').digest('hex')
   const own = fileDigest(join(project.root, target.file))
@@ -93,6 +109,14 @@ export function contentHash(project: LocalProject, target: SyncTarget): string |
     hash.update(treeHash(join(project.root, 'functions')) ?? '').update(treeHash(join(project.root, 'vendor')) ?? '')
     for (const path of importedFiles(project.root, target.file).filter((p) => !p.startsWith('functions/')).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) hash.update(path).update('\0').update(fileDigest(join(project.root, path)) ?? '')
   }
+  // The bases it picks, by their ids here: a base made again (after a reset) sets its picks again.
+  if (target.kind === 'agent') {
+    const picks = agentPicksIn(join(project.root, target.file))
+    if (picks) {
+      const ids = appliedBaseIds(project.stateDir)
+      hash.update(JSON.stringify(picks.map((p) => ids[pickedFolder(p) ?? ''] ?? null)))
+    }
+  }
   // Context and data the pull could not read is assumed on the project's object types: a new one changes it.
   if (target.kind === 'bindings' && /"blueprintUnread"\s*:\s*true/.test(readFileSync(join(project.root, target.file), 'utf8'))) {
     hash.update(treeHash(join(project.root, 'blueprint', 'object-types')) ?? '')
@@ -389,6 +413,10 @@ export function refOfTarget(target: SyncTarget): string {
       return `dataset/${target.apiName}`
     case 'knowledge':
       return `knowledge/${target.name}`
+    case 'knowledge-base':
+      return `${KNOWLEDGE_BASE_DIR}/${target.name}`
+    case 'knowledge-base-settings':
+      return 'knowledge-base-settings'
     case 'skill':
       return `skill/${target.name}`
     case 'plugin':

package/src/local/local-build-summary.ts

@@ -474,6 +474,7 @@ export function itemKindsText(rows: BuildRow[]): string {
     sharedField: ['shared field', 'shared fields'], objectSet: ['saved object set', 'saved object sets'], action: ['governed Action', 'governed Actions'],
     knowledge: ['knowledge base', 'knowledge bases'], skill: ['skill', 'skills'], plugin: ['Plugin', 'Plugins'], theme: ['slide theme', 'slide themes'],
     'chat-app': ['Chat App', 'Chat Apps'], app: ['Custom App', 'Custom Apps'], 'mcp-server': ['MCP server', 'MCP servers'],
+    'knowledge-base': ['knowledge base', 'knowledge bases'], 'knowledge-base-settings': ['Knowledge settings', 'Knowledge settings'],
   }
   const counts = new Map<string, number>()
   for (const r of rows) {

package/src/local/local-component-health.ts

@@ -1,7 +1,8 @@
 import { connect } from 'node:net'
 
 import { containerState } from './local-docker'
-import { isAlive, type ComponentName, type ComponentState, type LocalState } from './local-state'
+import { searchIndexHealth } from './local-search-index'
+import { COMPONENTS, isAlive, type ComponentName, type ComponentState, type LocalState } from './local-state'
 
 /**
  * Whether each part of a running local runtime is up now, not what the state
@@ -15,6 +16,8 @@ export interface ComponentProbe {
   container: (name: string) => ReturnType<typeof containerState>
   port: (port: number) => Promise<boolean>
   alive: (pid: number) => boolean
+  /** The search index's cluster health: null when usable, else why not. Without it, its port decides. */
+  searchIndex?: (port: number) => Promise<string | null>
 }
 
 /** A part of the runtime that is down, and why, in words. `cache` is the service's Redis, not a listed component. */
@@ -49,6 +52,7 @@ const defaultProbe: ComponentProbe = {
   },
   port: (port) => portAnswers(port),
   alive: isAlive,
+  searchIndex: (port) => searchIndexHealth(port),
 }
 
 const containerOf = (state: LocalState, c: ComponentState) => c.container ?? `frontera-${state.projectId}-${c.name}`
@@ -63,6 +67,7 @@ async function whyDown(state: LocalState, c: ComponentState, probe: ComponentPro
   } else if (!state.supervisorPid || !probe.alive(state.supervisorPid)) {
     return 'the supervisor exited'
   }
+  if (c.name === 'search-index' && c.port && probe.searchIndex) return probe.searchIndex(c.port)
   if (c.port && !(await probe.port(c.port))) return `nothing answers on its port ${c.port}`
   return null
 }
@@ -108,7 +113,7 @@ export async function downToRestart(state: LocalState, probe: ComponentProbe = d
   return down.length ? down : null
 }
 
-const ORDER: Array<DownComponent['name']> = ['postgres', 'cache', 'storage', 'service', 'jobs', 'runner', 'studio']
+const ORDER = COMPONENTS.flatMap((name): Array<DownComponent['name']> => (name === 'postgres' ? [name, 'cache'] : [name]))
 
 /** What brings a down component back, said on its line. */
 export const BRING_BACK = '`frontera local start` brings it back (the data is kept)'

package/src/local/local-dev-references.ts

@@ -344,10 +344,14 @@ export async function resolveTarget(
   } catch (err) {
     return { ok: false, output: `error [USAGE]: ${target.file} could not be read: ${(err as Error).message}` }
   }
+  // The Agent's Knowledge app bases are set after it applies (`applyAgentKnowledgeBases`), outside its draft,
+  // whose format has no such key: the copy `agent apply` sends goes without it.
+  const picks = target.kind === 'agent' && !!doc && typeof doc === 'object' && 'knowledgeBases' in doc
+  if (picks) delete (doc as Record<string, unknown>).knowledgeBases
   const modelSlugs = target.kind === 'agent' && (Array.isArray((doc as { modelConfigs?: unknown[] })?.modelConfigs) || typeof (doc as { config?: { voice?: { voiceSlug?: unknown } } })?.config?.voice?.voiceSlug === 'string')
   const mcpServers = target.kind === 'agent' && Array.isArray((doc as { mcpServers?: unknown[] })?.mcpServers) && (doc as { mcpServers: unknown[] }).mcpServers.length > 0
   const objectTools = target.kind === 'agent' && Array.isArray((doc as { objectBindings?: unknown[] })?.objectBindings) && (doc as { objectBindings: unknown[] }).objectBindings.length > 0
-  if (!kindsIn(doc).size && !modelSlugs && !mcpServers && !objectTools && !governedActionIds(doc).length && !(target.kind === 'workflow' && workflowNeedsLocalizing(doc))) return { ok: true, output: '', doc }
+  if (!picks && !kindsIn(doc).size && !modelSlugs && !mcpServers && !objectTools && !governedActionIds(doc).length && !(target.kind === 'workflow' && workflowNeedsLocalizing(doc))) return { ok: true, output: '', doc }
   const dir = await directory()
   const warnings: string[] = []
   // Built-in connections the project has stand-ins for (`local-stand-ins.ts`).
@@ -432,7 +436,7 @@ export async function resolveTarget(
     }
   }
   if (target.kind === 'operating') return { ok: true, doc: resolved, output: warnings.join('\n') }
-  if (!kindsIn(doc).size && !warnings.length && JSON.stringify(resolved) === JSON.stringify(readDoc(path))) return { ok: true, output: '', doc }
+  if (!picks && !kindsIn(doc).size && !warnings.length && JSON.stringify(resolved) === JSON.stringify(readDoc(path))) return { ok: true, output: '', doc }
   const copy = join('.frontera', 'local', 'resolved', target.file)
   mkdirSync(dirname(join(project.root, copy)), { recursive: true })
   writeFileSync(join(project.root, copy), /\.json$/.test(target.file) ? `${JSON.stringify(resolved, null, 2)}\n` : stringifyYaml(resolved, { lineWidth: 0 }))

package/src/local/local-dev-sync.ts

@@ -2,6 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 
 import { agentIdentity, createFlags } from './local-agent-name'
+import { KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_DOCUMENTS_DIR, KNOWLEDGE_BASE_FILE, KNOWLEDGE_BASE_SETTINGS_FILE, KNOWLEDGE_BASE_SOURCES_DIR } from './local-knowledge-base-files'
 import { widerGrants, type WorkspaceGrant } from './local-workspace-grants'
 
 /**
@@ -20,6 +21,8 @@ import { widerGrants, type WorkspaceGrant } from './local-workspace-grants'
  *   functions/<name>/ (with package.json) → function deploy <its entry>   (a Function deployed from its own folder)
  *   blueprint/**                        → blueprint apply --yes, then publish and grant (organization profile)
  *   knowledge/<name>/knowledge.json     → knowledge create, then upload the folder's new documents
+ *   knowledge-base/<name>/              → the Knowledge app's base, its sources and documents (local-knowledge-base-apply.ts)
+ *   knowledge-base/settings.json        → the organization's Knowledge settings
  *   skills/<name>/SKILL.md              → skill push skills/<name>
  *   mcp/<name>.plugin.json              → plugin add mcp (or configure), tools enabled
  *   mcp/<name>.stand-in.json            → a stand-in Plugin for a built-in connection: its tools answer “not connected”
@@ -49,6 +52,9 @@ export type SyncTarget =
   | { kind: 'function'; key: string; file: string }
   | { kind: 'blueprint'; key: string }
   | { kind: 'knowledge'; key: string; name: string; file: string }
+  /** A base in the Knowledge app: `file` is its knowledge-base.json; its sources and documents are in its folder. */
+  | { kind: 'knowledge-base'; key: string; name: string; file: string }
+  | { kind: 'knowledge-base-settings'; key: string; file: string }
   | { kind: 'skill'; key: string; name: string; file: string }
   | { kind: 'plugin'; key: string; name: string; file: string }
   | { kind: 'theme'; key: string; name: string; file: string }
@@ -112,6 +118,13 @@ export function targetFor(root: string, absolute: string): SyncTarget | null {
   if (top === 'knowledge' && parts.length >= 3 && second && existsSync(join(root, 'knowledge', second, 'knowledge.json'))) {
     return { kind: 'knowledge', key: `knowledge:${second}`, name: second, file: join('knowledge', second, 'knowledge.json') }
   }
+  if (top === KNOWLEDGE_BASE_DIR && parts.length === 2 && second === KNOWLEDGE_BASE_SETTINGS_FILE) {
+    return { kind: 'knowledge-base-settings', key: 'knowledge-base-settings', file: rel }
+  }
+  // A Knowledge app base is its file, its sources and its documents.
+  if (top === KNOWLEDGE_BASE_DIR && second && existsSync(join(root, KNOWLEDGE_BASE_DIR, second, KNOWLEDGE_BASE_FILE)) && isKnowledgeBaseFile(parts.slice(2))) {
+    return { kind: 'knowledge-base', key: `knowledge-base:${second}`, name: second, file: join(KNOWLEDGE_BASE_DIR, second, KNOWLEDGE_BASE_FILE) }
+  }
   if (top === 'skills' && parts.length >= 3 && second && existsSync(join(root, 'skills', second, 'SKILL.md'))) {
     return { kind: 'skill', key: `skill:${second}`, name: second, file: join('skills', second, 'SKILL.md') }
   }
@@ -154,6 +167,14 @@ export function targetFor(root: string, absolute: string): SyncTarget | null {
   return null
 }
 
+/** The files of a base's folder `local dev` applies: knowledge-base.json, `sources/<source>.json` and anything under `documents/`. */
+function isKnowledgeBaseFile(inFolder: string[]): boolean {
+  const [first, second] = inFolder
+  if (inFolder.length === 1) return first === KNOWLEDGE_BASE_FILE
+  if (first === KNOWLEDGE_BASE_SOURCES_DIR) return inFolder.length === 2 && !!second?.endsWith('.json')
+  return first === KNOWLEDGE_BASE_DOCUMENTS_DIR
+}
+
 /**
  * The entry of a Function kept in its own folder: the TypeScript file whose
  * `automation({ name: … })` names the folder, else index.ts or src/index.ts.
@@ -229,11 +250,12 @@ export function allTargets(root: string): SyncTarget[] {
       }
     }
   }
-  for (const top of ['datasets', 'blueprint', 'knowledge', 'skills', 'mcp', 'themes', 'functions', 'workflows', 'agents', 'chat-apps', 'apps', 'mcp-servers', 'brand']) walk(join(root, top), 1)
+  for (const top of ['datasets', 'blueprint', 'knowledge', KNOWLEDGE_BASE_DIR, 'skills', 'mcp', 'themes', 'functions', 'workflows', 'agents', 'chat-apps', 'apps', 'mcp-servers', 'brand']) walk(join(root, top), 1)
   if (existsSync(join(root, 'library.json'))) out.set('library', { kind: 'library', key: 'library', file: 'library.json' })
   // Datasets first (object types read them), then the Blueprint (Agents and
   // workflows read its objects), then what Agents use by name (knowledge
-  // bases and slide themes, skills, plugins), then Functions (workflows and
+  // bases, the Knowledge settings before the Knowledge app's bases whose
+  // sources they allow, slide themes, skills, plugins), then Functions (workflows and
   // Agents call them), then Agents (a workflow's agent step names one), then workflows, then what
   // each Agent may start, then the Agents' behavior settings (a procedure runs
   // only what its Agent may start), then the Chat Apps their Agents are used in and the Apps that
@@ -242,7 +264,7 @@ export function allTargets(root: string): SyncTarget[] {
   return [...out.values()].sort(byApplyOrder)
 }
 
-const ORDER = { brand: -1, dataset: 0, blueprint: 1, knowledge: 2, theme: 2, skill: 3, plugin: 4, function: 5, agent: 6, workflow: 7, bindings: 8, operating: 9, lessons: 9, 'chat-app': 10, app: 10, 'mcp-server': 10, library: 11 }
+const ORDER = { brand: -1, dataset: 0, blueprint: 1, knowledge: 2, 'knowledge-base-settings': 2, theme: 2, 'knowledge-base': 3, skill: 3, plugin: 4, function: 5, agent: 6, workflow: 7, bindings: 8, operating: 9, lessons: 9, 'chat-app': 10, app: 10, 'mcp-server': 10, library: 11 }
 
 /** Dependencies first: what a later kind reads or calls is applied before it. */
 export function byApplyOrder(a: SyncTarget, b: SyncTarget): number {
@@ -297,6 +319,8 @@ export function commandFor(target: SyncTarget, profiles: SyncProfiles): string[]
       // Session-only route; `local dev` calls it itself (see local-operating.ts).
       throw new Error('behavior settings are applied over the API, not with a CLI command')
     case 'knowledge':
+    case 'knowledge-base':
+    case 'knowledge-base-settings':
     case 'plugin':
     case 'bindings':
     case 'theme':
@@ -437,6 +461,10 @@ export function describeTarget(target: SyncTarget): string {
       return 'Blueprint'
     case 'knowledge':
       return `knowledge base ${target.name}`
+    case 'knowledge-base':
+      return `${KNOWLEDGE_BASE_DIR}/${target.name}`
+    case 'knowledge-base-settings':
+      return 'the Knowledge settings'
     case 'skill':
       return `skill ${target.name}`
     case 'plugin':
@@ -505,6 +533,11 @@ export function unappliedReason(root: string, rel: string): string | null {
     case 'knowledge':
       if (parts.length === 2) return 'a knowledge base is a folder: knowledge/<name>/knowledge.json ({ "name": "…", "description": "…" }) with its documents beside it'
       return `knowledge/${second}/ has no knowledge.json ({ "name": "…", "description": "…" }), so its documents are not uploaded`
+    case KNOWLEDGE_BASE_DIR:
+      if (parts.length === 2) return `a knowledge base is a folder: ${KNOWLEDGE_BASE_DIR}/<name>/${KNOWLEDGE_BASE_FILE}, with its API sources in sources/ and its files in documents/; the one file beside the folders is ${KNOWLEDGE_BASE_SETTINGS_FILE} (\`frontera local schema knowledge-base\`)`
+      if (!existsSync(join(root, KNOWLEDGE_BASE_DIR, second!, KNOWLEDGE_BASE_FILE))) return `${KNOWLEDGE_BASE_DIR}/${second}/ has no ${KNOWLEDGE_BASE_FILE}, so nothing in it is applied (\`frontera local schema knowledge-base\`)`
+      if (parts[2] === KNOWLEDGE_BASE_SOURCES_DIR) return `a source is ${KNOWLEDGE_BASE_DIR}/${second}/${KNOWLEDGE_BASE_SOURCES_DIR}/<source>.json, directly in ${KNOWLEDGE_BASE_SOURCES_DIR}/ (\`frontera local schema knowledge-base-source\`)`
+      return `a knowledge base folder holds ${KNOWLEDGE_BASE_FILE}, ${KNOWLEDGE_BASE_SOURCES_DIR}/ and ${KNOWLEDGE_BASE_DOCUMENTS_DIR}/: put the files to upload in ${KNOWLEDGE_BASE_DIR}/${second}/${KNOWLEDGE_BASE_DOCUMENTS_DIR}/`
     case 'skills':
       if (parts.length === 2) return 'a skill is a folder: skills/<name>/SKILL.md'
       return `skills/${second}/ has no SKILL.md, so it is not pushed`
@@ -546,6 +579,12 @@ export function unappliedFiles(root: string): string[] {
         const [top, second] = rel.split(sep)
         // Folders whose files are not each applied: a Function's helpers, a knowledge base's documents, an App's code.
         if (top === 'functions' || top === 'apps' || (top === 'knowledge' && second && existsSync(join(root, 'knowledge', second, 'knowledge.json')))) continue
+        // A base's documents are each uploaded; a folder without knowledge-base.json is one line.
+        if (top === KNOWLEDGE_BASE_DIR && rel.split(sep)[2] === KNOWLEDGE_BASE_DOCUMENTS_DIR) continue
+        if (top === KNOWLEDGE_BASE_DIR && second && rel.split(sep).length === 2 && !existsSync(join(root, KNOWLEDGE_BASE_DIR, second, KNOWLEDGE_BASE_FILE))) {
+          out.push(`${rel}/: ${unappliedReason(root, join(rel, '_'))}`)
+          continue
+        }
         if (top === 'skills' && second && existsSync(join(root, 'skills', second, 'SKILL.md'))) continue
         if (top === 'themes' && second && existsSync(join(root, 'themes', second, 'theme.json'))) continue
         if (top === 'knowledge' || top === 'skills' || top === 'themes') {
@@ -562,6 +601,6 @@ export function unappliedFiles(root: string): string[] {
       }
     }
   }
-  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', 'mcp', 'mcp-servers', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
+  for (const top of ['agents', 'blueprint', 'chat-apps', 'datasets', 'knowledge', KNOWLEDGE_BASE_DIR, 'mcp', 'mcp-servers', 'skills', 'themes', 'workflows']) walk(join(root, top), 1)
   return out
 }