@frontera-sdk/cli 1.53.23 → 1.53.25

package/src/commands/local/dev.ts

@@ -76,6 +76,9 @@ import { applyApp } from '../../local/local-apps'
 import { applyBrand, brandUpload } from '../../local/local-brand'
 import { applyLibrary } from '../../local/local-library'
 import { projectFileChecks } from '../../local/local-file-checks'
+import { applyAgentKnowledgeBases, applyKnowledgeBase, applyKnowledgeSettings, knowledgeBaseCalls, knowledgeBasesOff, knowledgeOffOutput, movedCredentials, removeDeletedBases } from '../../local/local-knowledge-base-apply'
+import { readKeptSchema } from '../../local/local-schemas'
+import { readProviderSetup } from '../../local/local-providers'
 import { actionFailureLines, dedupeLines, hasIndexedPaths, nameIndexedPaths, refusedArtifact, refusedByRules, sourceSystemHint } from '../../local/local-blueprint-errors'
 
 /**
@@ -192,7 +195,7 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
   // What the Agent's files say that would apply in silence and fail in a chat (`local-agent-checks.ts`).
   const agent = agentChecks(project, target)
   // A Chat App, knowledge base or skill against its format: a key the platform drops is said, a wrong shape refused.
-  const formats = projectFileChecks(project.root, target as { kind: string; file?: string })
+  const formats = projectFileChecks(project.root, target as { kind: string; file?: string }, (kind) => readKeptSchema(project, kind))
   const checked = { errors: [...agent.errors, ...formats.errors], warnings: [...agent.warnings, ...formats.warnings] }
   if (checked.errors.length) return { ok: false, output: [`error [USAGE]: ${describeTarget(target)} can't be applied as written`, ...checked.errors.map((e) => `  ${e}`), ...checked.warnings].join('\n') }
   const resolved = await resolveTarget(project, target, lookup, creds?.workspaceId, creds?.organizationId)
@@ -217,6 +220,15 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     if (!creds) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
     return withNotes(await applyBindings(project, target, opts.serviceUrl, creds))
   }
+  if (target.kind === 'knowledge-base' || target.kind === 'knowledge-base-settings') {
+    if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
+    // As the runtime's owner, a Knowledge steward: an organization base is made at the organization level.
+    const call = knowledgeBaseCalls(opts.serviceUrl, creds)
+    const off = await knowledgeBasesOff(readState(project)?.components, call)
+    if (off) return { ok: false, output: knowledgeOffOutput(off) }
+    if (target.kind === 'knowledge-base-settings') return withNotes(await applyKnowledgeSettings(project.root, { call, workspaceId: creds.workspaceId, preferredModel: readProviderSetup().defaults.agentModel ?? null }))
+    return withNotes(await applyKnowledgeBase(project, target.name, { call, organizationId: creds.organizationId, workspaceId: creds.workspaceId, secrets: await localSecretPresence(opts.serviceUrl, creds) }))
+  }
   if (target.kind === 'knowledge') return withNotes(await applyKnowledge(project, target, profiles, (args) => runCli(project, args, opts.auth), creds ? { serviceUrl: opts.serviceUrl, creds } : undefined))
   if (target.kind === 'theme') {
     if (!creds?.session) return { ok: false, output: 'error [LOCAL_NOT_SEEDED]: the runtime is not seeded yet' }
@@ -431,6 +443,14 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     // Agents stay drafts here, so the row keeps the name it was created with unless set from the file.
     const named = await syncAgentName({ slug: target.slug, identity: agentIdentity(project.root, target.file), serviceUrl: opts.serviceUrl, creds })
     if (named) result = { ...result, output: `${result.output}\n${named}`.trim() }
+    // Its Knowledge app bases (`knowledgeBases`): set live, outside the draft, once the Agent is here.
+    if (creds.session) {
+      const call = knowledgeBaseCalls(opts.serviceUrl, creds)
+      const found = await call('workspace', 'GET', `/v1/config/agents/${encodeURIComponent(target.slug)}`).catch(() => ({ status: 0, body: null }))
+      const agentId = found.status === 200 ? ((found.body as { data?: { id?: string } } | null)?.data?.id ?? null) : null
+      const picks = await applyAgentKnowledgeBases(project, original.file, agentId, call)
+      if (picks.length) result = { ...result, output: [result.output, ...picks].join('\n').trim() }
+    }
   }
   let authoredAgain: string[] = []
   if (actionCalls && blueprint) {
@@ -928,7 +948,14 @@ async function dev(ctx: CommandContext) {
     const embeddings = target.kind === 'knowledge' ? ((await embeddingsDiffer(project.root, { serviceUrl, creds }).catch((): false => false)) || ('same' as const)) : undefined
     const embeddingsMoved = !!embeddings && !!hash && applied.get(target.key) === hash && (recorded?.embeddings ?? 'same') !== embeddings
     if (embeddingsMoved) ctx.output.note(`  ${describeTarget(target)}: the runtime’s embeddings changed since it was applied (${embeddingWords(recorded?.embeddings ?? 'same')} then, ${embeddingWords(embeddings!)} now): applying it again so its threshold follows`)
-    if (hash && applied.get(target.key) === hash && !draftGone && !actionsDown.length && !versionUnknown && !embeddingsMoved) {
+    // A Knowledge app base, or the Knowledge settings, while the runtime's search index is off: unchanged files,
+    // but nothing here can search the base, so it is applied, and fails saying why and what to run.
+    const knowledgeOff = (target.kind === 'knowledge-base' || target.kind === 'knowledge-base-settings') && !!hash && applied.get(target.key) === hash && !!creds.session && !!(await knowledgeBasesOff(readState(project)?.components, knowledgeBaseCalls(serviceUrl, creds)))
+    // A base whose source signs in with a secret set, or taken away, on the runtime since it was applied (`frontera secret set`):
+    // unchanged files, but it is applied again so the source signs in with the value there now.
+    const secretsMoved = target.kind === 'knowledge-base' && !!hash && applied.get(target.key) === hash && !knowledgeOff ? await movedCredentials(project, target.name, organizationId, () => localSecretPresence(serviceUrl, creds)) : []
+    if (secretsMoved.length) ctx.output.note(`  ${describeTarget(target)}: ${secretsMoved.join(', ')} changed on the runtime since it was applied: applying it again so its sources sign in with the value there now`)
+    if (hash && applied.get(target.key) === hash && !draftGone && !actionsDown.length && !versionUnknown && !embeddingsMoved && !knowledgeOff && !secretsMoved.length) {
       unchanged += 1
       // An Agent applied before names were set from its file still reads its slug: set it once.
       if (target.kind === 'agent' && !named.has(target.slug)) {
@@ -1069,6 +1096,8 @@ async function dev(ctx: CommandContext) {
   let secretsDue = false
   /** Whether to deploy again the Custom Apps a database restore took away (`local-app-restore.ts`): at the start, and after a restore. */
   let appsDue = true
+  /** Whether to look for knowledge-base/ folders deleted since their base was made (`removeDeletedBases`): at the start, and after one goes. */
+  let basesDue = true
 
   /**
    * A Custom App deployed after the baseline a restore went back to is not on
@@ -1183,6 +1212,13 @@ async function dev(ctx: CommandContext) {
         appsDue = false
         await redeployRestoredApps()
       }
+      // After this round's applies, so a renamed folder has found its base by its name first. A base folder
+      // here that fails to apply may be one renamed: the pass waits for it, still due.
+      const baseFailing = [...failing.keys()].some((key) => key.startsWith('knowledge-base:') && existsSync(join(project.root, 'knowledge-base', key.slice('knowledge-base:'.length))))
+      if (basesDue && !stopping && !runtimeDown && !baseFailing) {
+        basesDue = false
+        await removeDeletedKnowledgeBases()
+      }
     } finally {
       busy = false
       if (round.since) {
@@ -1363,6 +1399,27 @@ async function dev(ctx: CommandContext) {
     }
   }
 
+  /** The knowledge bases this project made here whose folder was deleted: removed, said, and forgotten as applied, so a folder put back is applied again. */
+  const removeDeletedKnowledgeBases = async (): Promise<void> => {
+    if (!creds?.session) return
+    try {
+      const { lines, removed, kept } = await removeDeletedBases(project, organizationId, knowledgeBaseCalls(serviceUrl, creds), readState(project)?.components)
+      for (const line of lines) ctx.output.note(line)
+      // A base kept for a folder that has not applied yet: looked at again after the next round.
+      if (kept.length) basesDue = true
+      if (!removed.length) return
+      const known = loadHashes(project, organizationId)
+      for (const key of removed.map((folder) => `knowledge-base:${folder}`)) {
+        applied.delete(key)
+        known.delete(key)
+      }
+      saveHashes(project, organizationId, known)
+      recordApplied(project, { at: new Date().toISOString(), what: removed.map((folder) => `knowledge-base/${folder}`).join(', '), ok: true })
+    } catch (err) {
+      ctx.output.note(`  warning: the knowledge bases of deleted knowledge-base/ folders couldn’t be checked: ${(err as Error).message}`)
+    }
+  }
+
   // Watch from the start, so a save during the first sync is not missed.
   const once = flagBool(ctx, 'once')
   // One watcher per project (Forge keeps one running; a second would apply every change twice). `--once` is always allowed.
@@ -1390,6 +1447,11 @@ async function dev(ctx: CommandContext) {
         // An Agent's folder, a workflow's or a Function's file deleted: what the runtime holds follows.
         if (/^(agents|workflows|functions)([\\/]|$)/.test(filename.toString()) && !existsSync(join(project.root, filename.toString()))) void sweepOrphans()
         if (/^agents[\\/][^\\/]+[\\/]operating\.json$/.test(filename.toString()) && !existsSync(join(project.root, filename.toString()))) void clearDeletedBehavior()
+        // Something under knowledge-base/ deleted: a base folder gone goes from the runtime after the next round.
+        if (/^knowledge-base[\\/]/.test(filename.toString()) && !existsSync(join(project.root, filename.toString()))) {
+          basesDue = true
+          if (!busy) schedule()
+        }
         // Only a change that queued an item starts a round: the watcher's own writes under `.frontera/`,
         // a screenshot, a coding agent's settings or a note in docs/ never do.
         if (queuePath(filename.toString()) && !busy) schedule()

package/src/commands/local/index-commands.ts

@@ -15,7 +15,7 @@ import { findObjectSet, normalizeObjectSets, projectObjectSetNames } from '../..
 import { actionsStatusText, appsStatusText, buildStatusText, emptyKnowledgeLines, itemKindsText, notPulledLines, objectSetsStatusText, projectBuildRows, projectBuildSummary, projectFilesLines } from '../../local/local-build-summary'
 import { inheritedActionWarnings } from '../../local/local-check-inherited'
 import { checkoutVersion, docsStatus, versionAtStart } from '../../local/local-docs'
-import { dockerAvailable } from '../../local/local-docker'
+import { dockerAvailable, dockerMemoryBytes } from '../../local/local-docker'
 import { downPhase, downToRestart, liveComponents, type DownComponent } from '../../local/local-component-health'
 import { readConfig, writeConfig, type LocalConfig } from '../../local/local-env'
 import { configuredProviders } from '../../local/local-keys'
@@ -31,7 +31,8 @@ import {
   stopRuntime,
   waitForPhase,
 } from '../../local/local-control'
-import { clearState, ensureStateDir, isAlive, logPath, readState, type ComponentName, type LocalState } from '../../local/local-state'
+import { clearState, COMPONENTS, ensureStateDir, isAlive, logPath, readState, type ComponentName, type LocalState } from '../../local/local-state'
+import { searchIndexChoice, searchIndexNeeds } from '../../local/local-search-index'
 import { newSessionToken } from '../../local/local-studio-server'
 import { migrateMcpConfigs } from '../../local/local-scaffold'
 import { DEFAULT_REGISTRY, runSupervisor } from '../../local/local-supervisor'
@@ -79,8 +80,9 @@ import { readLock, recentWriters, writerWords } from '../../local/local-writers'
  * Frontera Studio on top of it. Nothing here talks to a Frontera deployment.
  */
 
-const COMPONENTS: ComponentName[] = ['postgres', 'storage', 'service', 'jobs', 'runner', 'studio']
-const OPTIONAL: ComponentName[] = ['jobs', 'runner', 'storage']
+const OPTIONAL: ComponentName[] = ['jobs', 'runner', 'storage', 'search-index']
+/** Off unless the project needs it or `--with` names it. */
+const ON_REQUEST: ComponentName[] = ['search-index']
 
 const sessionFile = (project: LocalProject) => join(project.stateDir, 'studio-session')
 
@@ -126,10 +128,10 @@ function renderStatus(state: LocalState, project: LocalProject, profile?: { prof
   for (const c of state.components) {
     const where = c.kind === 'container' ? 'container' : c.kind === 'process' ? 'process' : 'supervisor'
     const status = down.some((d) => d.name === c.name) ? 'down' : c.status
-    lines.push(`  ${DOT[status] ?? '·'} ${c.name.padEnd(9)} ${status.padEnd(9)} ${c.status === 'off' ? (c.detail ?? '') : where}${c.status === 'failed' && c.detail ? ` — ${c.detail}` : ''}`)
+    lines.push(`  ${DOT[status] ?? '·'} ${c.name.padEnd(12)} ${status.padEnd(9)} ${c.status === 'off' ? (c.detail ?? '') : where}${c.status === 'failed' && c.detail ? ` — ${c.detail}` : ''}`)
   }
   const cache = down.find((d) => d.name === 'cache')
-  if (cache) lines.push(`  ✕ ${'cache'.padEnd(9)} ${'down'.padEnd(9)} container — ${cache.why}; \`frontera local start\` brings it back`)
+  if (cache) lines.push(`  ✕ ${'cache'.padEnd(12)} ${'down'.padEnd(9)} container — ${cache.why}; \`frontera local start\` brings it back`)
   if (state.credentials) {
     lines.push('')
     lines.push(`  Signed in as ${state.credentials.email}`)
@@ -222,6 +224,17 @@ function parseList(raw: string | undefined): ComponentName[] {
   return names
 }
 
+function parseWith(raw: string | undefined): ComponentName[] {
+  if (!raw) return []
+  const names = raw.split(',').map((s) => s.trim()).filter(Boolean) as ComponentName[]
+  for (const n of names) {
+    if (!ON_REQUEST.includes(n)) {
+      throw new UsageError(`\`${n}\` cannot be added with --with`, `only ${ON_REQUEST.join(', ')} starts on request; the other components run unless excluded`)
+    }
+  }
+  return names
+}
+
 async function start(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const project = localProject(ctx.cwd)
   // Coding-agent configs from before `frontera mcp` launched the documentation server alone.
@@ -262,13 +275,21 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
   if (sourceFlag && !isPlatformSource(source!)) {
     throw new UsageError(`${source} is not a Frontera platform checkout`, 'point --source at the repository root that holds packages/service')
   }
-  const exclude = keep && !flagString(ctx, 'exclude') ? previous!.exclude : parseList(flagString(ctx, 'exclude'))
+  const exclude: string[] = keep && !flagString(ctx, 'exclude') ? previous!.exclude : parseList(flagString(ctx, 'exclude'))
+  const added: string[] = keep && !flagString(ctx, 'with') ? (previous!.with ?? []) : parseWith(flagString(ctx, 'with'))
+  const both = added.find((n) => exclude.includes(n))
+  if (both) throw new UsageError(`\`${both}\` is both added with --with and excluded`, `pass one of \`--with ${both}\` and \`--exclude ${both}\``)
+  // The supervisor decides the same way when it starts it.
+  const searchIndex = searchIndexChoice({ root: project.root, with: added, exclude, dockerMemoryBytes: dockerMemoryBytes() })
+  const needs = searchIndex.on ? searchIndexNeeds(exclude) : null
+  if (needs) throw new UsageError(needs, 'the search index runs for a project with a knowledge-base/ folder, or with `--with search-index`')
   const config: LocalConfig = {
     mode: source ? 'source' : 'image',
     platformSource: source ?? undefined,
     platformVersion: versionAtStart({ checkout: source ? checkoutVersion(source) : null, flag: flagString(ctx, 'version'), previous, cli: cliVersion() }),
     registry: normalizeRegistry(flagString(ctx, 'registry') ?? process.env.FRONTERA_LOCAL_REGISTRY ?? previous?.registry),
     exclude,
+    ...(added.length ? { with: added } : {}),
   }
   ensureStateDir(project)
   writeConfig(project, config)
@@ -277,7 +298,7 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
   const freed = reclaimedNote(reclaimed)
   if (freed) ctx.output.note(freed)
   for (const name of [...COMPONENTS, 'cache', 'embeddings', 'traces'] as const) {
-    if (exclude.includes(name as ComponentName)) continue
+    if (exclude.includes(name) || (name === 'search-index' && !searchIndex.on)) continue
     if (!(await isPortFree(ports[name]))) {
       const holder = portHolder(ports[name])
       throw new CliError(`port ${ports[name]} (${name}) is already in use${holder ? ` by ${holder}` : ''}`, {
@@ -322,9 +343,12 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
 
 const startMeta = {
   args: [],
-  flags: { source: 'string', image: 'boolean', version: 'string', registry: 'string', exclude: 'string' },
+  flags: { source: 'string', image: 'boolean', version: 'string', registry: 'string', exclude: 'string', with: 'string' },
   summary: 'Start Frontera\'s runtimes on this machine and seed an owner, workspace and keys',
-  examples: ['frontera local start', 'frontera local start --exclude runner', 'frontera local start --image --version 1.52.19', 'frontera local start --image --registry registry.example.com/frontera'],
+  details: [
+    'The search index (for knowledge bases) runs when the project has a knowledge-base/ folder, or with `--with search-index`; `--exclude search-index` keeps it off. It needs storage and jobs, and Docker with about 6 GB of memory (Docker Desktop: Settings > Resources > Memory limit): with less it stays off and `frontera local status` says so.',
+  ],
+  examples: ['frontera local start', 'frontera local start --exclude runner', 'frontera local start --with search-index', 'frontera local start --image --version 1.52.19', 'frontera local start --image --registry registry.example.com/frontera'],
   offline: true,
 } as const
 

package/src/commands/local/init.ts

@@ -27,6 +27,13 @@ import { localSync } from './sync'
  * kinds, and sample data for the pulled Blueprint. `frontera local start`
  * then runs it, and `local dev` applies what was pulled.
  */
+/**
+ * Everything a solution is made of: Apps, Chat Apps and slide themes too, so a
+ * pulled project has what the workspace lists. Knowledge bases come without
+ * their documents, and a platform that does not take them pulls none.
+ */
+const FROM_WORKSPACE_KINDS = 'blueprint,skills,functions,plugins,knowledge,knowledge-bases,workflows,agents,evaluations,themes,chat-apps,apps'
+
 export const localInit: Command = {
   meta: {
     noun: 'local',
@@ -46,6 +53,9 @@ export const localInit: Command = {
       rows: 'string',
       seed: 'string',
     },
+    flagHelp: {
+      kinds: `with --from-workspace, the kinds to pull, separated by commas (default: ${FROM_WORKSPACE_KINDS.split(',').join(', ')}); knowledge bases come without their documents (\`frontera local sync pull --documents knowledge-base/<name>\` brings them); \`none\` links the project and pulls nothing`,
+    },
     summary: 'Create a project: an Agent with a test case, a workflow, a Function and a Blueprint object type with its data',
     examples: [
       'frontera local init claims-intake',
@@ -158,8 +168,7 @@ async function startFromWorkspace(ctx: CommandContext, target: string): Promise<
   } else if (!readLink(target)) {
     throw new UsageError('no workspace to start from', 'pass --platform <url> --workspace-key - with the key on stdin')
   }
-  // Everything a solution is made of: Apps, Chat Apps and slide themes too, so a pulled project has what the workspace lists.
-  const kinds = flagString(ctx, 'kinds') ?? 'blueprint,skills,functions,plugins,knowledge,workflows,agents,evaluations,themes,chat-apps,apps'
+  const kinds = flagString(ctx, 'kinds') ?? FROM_WORKSPACE_KINDS
   // `none` links the project and pulls nothing, for someone who picks items next (`local sync pull <kind/name>…`).
   if (kinds === 'none') {
     const link = readLink(target)

package/src/commands/local/schema.ts

@@ -16,7 +16,7 @@ export const localSchema: Command = {
     verb: 'schema',
     args: [{ name: 'kind', required: false, description: SCHEMA_KINDS.join(' | ') }],
     flags: {},
-    summary: 'Print the JSON Schema of a project file (Agent, its bindings, workflow, tests, dataset, slide theme, Blueprint) for the runtime\'s release',
+    summary: 'Print the JSON Schema of a project file (Agent, its bindings, workflow, tests, dataset, slide theme, Blueprint, knowledge base) for the runtime\'s release',
     examples: ['frontera local schema', 'frontera local schema operating', 'frontera local schema workflow-tests', 'frontera local schema blueprint-action', 'frontera local schema bindings', "frontera local schema workflow | jq '.\"$defs\" | keys'"],
     offline: true,
   },

package/src/commands/local/sync-request.ts

@@ -13,7 +13,11 @@ import { mcpServersNotCarried } from '../../local/local-mcp-servers'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
-import { getSyncKey, readLink, registerTargetProfile, setModelMapping, targetLabel, targetOf, targetProfileName, targetSession, targetWords, type SyncLink, type SyncTarget } from '../../local/local-sync-link'
+import { getSyncKey, personReader, readLink, registerTargetProfile, setModelMapping, targetLabel, targetOf, targetProfileName, targetSession, targetWords, type SyncLink, type SyncTarget } from '../../local/local-sync-link'
+import { KNOWLEDGE_BASE_DIR } from '../../local/local-knowledge-base-files'
+import { KNOWLEDGE_SETTINGS_REF, knowledgeBaseDocumentsOn } from '../../local/local-knowledge-base-pull'
+import { sourcesOffNeeds } from '../../local/local-knowledge-base-sources-off'
+import type { PersonClients } from '../../local/local-sync-remote'
 import { itemTitle } from '../../local/local-sync-names'
 import { checkBody, markMissingModels, markRefused, movedOnTarget, needsAPerson, planOf, type ApplyStep, type WorkspaceModel } from '../../local/local-sync-precheck'
 import { afterApplyOf, recordAfterApply } from '../../local/local-person-steps'
@@ -86,6 +90,9 @@ function needLink(project: LocalProject): SyncLink {
   return link
 }
 
+/** An item as a line names it: its kind and title; the Knowledge settings by their title alone. */
+const labelOf = (i: { ref: string; kind: SyncKind; title: string }) => (i.ref === KNOWLEDGE_SETTINGS_REF ? i.title : `${KIND_WORD[i.kind]} ${i.title}`)
+
 const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
 
 // ── The platform ────────────────────────────────────────────────────────────
@@ -331,6 +338,8 @@ interface ViewItem {
   id: string
   ref: string
   kind: SyncKind
+  /** The platform's id of what the item became, once applied (a knowledge base Apply created). */
+  resourceId?: string | null
   /** What the item's candidate is: evidence taken for it is bound to it. */
   candidateDigest?: string
   name: string
@@ -547,12 +556,13 @@ function assetUploader(project: Pick<LocalProject, 'root'>, api: Platform) {
 async function stageDocuments(project: Pick<LocalProject, 'root'>, api: Platform, view: View): Promise<number> {
   let sent = 0
   for (const item of view.items) {
-    if (item.kind !== 'knowledge' || !item.documents) continue
+    if ((item.kind !== 'knowledge' && item.kind !== 'knowledge-base') || !item.documents) continue
     for (const doc of item.documents.upload) {
       if (doc.staged) continue
-      const path = documentPath(doc.folder, doc.fileName)
-      const bytes = new Uint8Array(readFileSync(join(project.root, 'knowledge', item.name, path)))
-      if (sha256Of(bytes) !== doc.sha256) throw new CliError(`knowledge/${item.name}/${path} changed while it was proposed`, { code: 'CONFLICT', hint: 'push again' })
+      // A Knowledge app base keeps its documents in `documents/`, with no folders.
+      const path = item.kind === 'knowledge' ? `knowledge/${item.name}/${documentPath(doc.folder, doc.fileName)}` : `${KNOWLEDGE_BASE_DIR}/${item.name}/documents/${doc.fileName}`
+      const bytes = new Uint8Array(readFileSync(join(project.root, path)))
+      if (sha256Of(bytes) !== doc.sha256) throw new CliError(`${path} changed while it was proposed`, { code: 'CONFLICT', hint: 'push again' })
       await api.send('PUT', `/v1/change-requests/${view.request.id}/documents/${doc.sha256}`, bytes, 'application/octet-stream', { timeoutMs: 300_000 })
       sent++
     }
@@ -578,6 +588,29 @@ async function platformDocuments(api: Platform, names: string[], remote: Array<{
   return out
 }
 
+/** What the workspace holds of each Knowledge app base whose documents are brought, read as the person signed in: its documents by name. */
+async function baseDocumentsOn(person: PersonClients | null, refs: string[], remote: Array<{ ref: string; id?: string }>): Promise<Map<string, Array<{ id: string; fileName: string }>>> {
+  const out = new Map<string, Array<{ id: string; fileName: string }>>()
+  for (const ref of refs) {
+    const id = remote.find((r) => r.ref === ref)?.id
+    out.set(ref, person && id ? await knowledgeBaseDocumentsOn(person.workspace, id) : [])
+  }
+  return out
+}
+
+/** The words for what a knowledge base step needs of the person applying (the platform's `knowledge_*` needs), as this CLI's next step. */
+function knowledgeNextStep(code: string, acting: Acting): string | null {
+  if (code === 'knowledge_needs_person') return `sign in with \`${signInCommand(acting.profile)}\` and push again, so the change request is yours to apply as yourself`
+  if (code === 'knowledge_needs_steward') return 'apply it signed in as a Knowledge steward, or ask one to apply it; an organization owner or admin names stewards (`frontera knowledge-base steward add`)'
+  if (code === 'knowledge_settings_need_admin') return 'ask an organization owner or admin to apply it, or take the parts only they set (searchModel, sources) out of knowledge-base/settings.json'
+  return null
+}
+
+/** What Apply needs of a person, each with this CLI's next step where it has its own. */
+function personNeeds(plan: ApplyStep[], acting: Acting): ReturnType<typeof needsAPerson> {
+  return needsAPerson(plan).map((n) => ({ ...n, fix: knowledgeNextStep(n.code, acting) ?? n.fix }))
+}
+
 /**
  * What still uses each item this push would delete, read with the platform's
  * own in-use check before anything is proposed, so a deletion names its
@@ -637,7 +670,7 @@ function changedThereLines(target: SyncTarget, changed: Array<{ ref: string; kin
   return [
     '',
     `Changed in ${targetLabel(target)} since this project last delivered it, so not proposed:`,
-    ...changed.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: to put the project’s version back over it, \`${targetWords(target, `frontera local sync resolve ${i.ref} --keep mine`)}\``),
+    ...changed.map((i) => `  ${labelOf(i)}: to put the project’s version back over it, \`${targetWords(target, `frontera local sync resolve ${i.ref} --keep mine`)}\``),
   ]
 }
 
@@ -653,13 +686,10 @@ function previewText(target: SyncTarget, items: PushItem[], kept: { title: strin
     // Each item's notes under it.
     ...ok.flatMap((i) => [`  [x] ${pushItemLine(i)}`, ...(usedBy.has(i.ref) ? [`      ! Still used by ${usedBy.get(i.ref)!.join(', ')}: applying would be refused`] : []), ...i.notes.map((n) => `      · ${n}`)]),
   ]
-  if (samples.length) lines.push('', 'Samples from setting up the project, left out unless named:', ...samples.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}`))
-  if (not.length) lines.push('', 'Not proposed:', ...not.flatMap((i) => [`  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]))
+  if (samples.length) lines.push('', 'Samples from setting up the project, left out unless named:', ...samples.map((i) => `  [ ] ${labelOf(i)}`))
+  if (not.length) lines.push('', 'Not proposed:', ...not.flatMap((i) => [`  [ ] ${labelOf(i)}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]))
   lines.push(...changedThereLines(target, changedThere))
-  const before = person.filter((p) => !p.after)
-  const after = person.filter((p) => p.after)
-  if (before.length) lines.push('', 'Needs a person before Apply:', ...before.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Fix: ${p.fix}`]))
-  if (after.length) lines.push('', 'Left for a person after Apply:', ...after.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Then: ${p.fix}`]))
+  lines.push(...needLines(person))
   if (orgNote) lines.push('', orgNote)
   if (notCarried) lines.push('', notCarried)
   if (!available) lines.push('', 'This platform does not take change requests yet.')
@@ -667,6 +697,16 @@ function previewText(target: SyncTarget, items: PushItem[], kept: { title: strin
   return lines.join('\n')
 }
 
+/** What Apply needs of a person, before it and after it, as the preview and the push say it. */
+function needLines(person: ReturnType<typeof needsAPerson>): string[] {
+  const before = person.filter((p) => !p.after)
+  const after = person.filter((p) => p.after)
+  return [
+    ...(before.length ? ['', 'Needs a person before Apply:', ...before.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Fix: ${p.fix}`])] : []),
+    ...(after.length ? ['', 'Left for a person after Apply:', ...after.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Then: ${p.fix}`])] : []),
+  ]
+}
+
 /**
  * The release items asked for: each App resolved in the workspace, and the
  * deployment named, or its newest one (what was deployed last, previews
@@ -729,20 +769,39 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   const command = (words: string) => targetWords(target, `frontera local sync ${words}`)
   // Fetch first, as git does before a push: an item the workspace moved past is pulled and merged first.
   // A named target is never pulled from: it is compared with what this project last delivered to it (`targetPlan`).
-  const { plan, lock, snapshot, remote, delivered } = target.name ? await targetPlan(project, target) : { ...(await planFor(project, link, { fetch: 'always', repair: 'online' })), delivered: null }
+  // A project with knowledge bases reads the whole index: the names Apply finds a base by can move without its revision.
+  const { plan, lock, snapshot, remote, delivered } = target.name ? await targetPlan(project, target) : { ...(await planFor(project, link, { fetch: 'always', repair: 'online', full: existsSync(join(project.root, KNOWLEDGE_BASE_DIR)) })), delivered: null }
   if (!plan || !snapshot) throw new CliError('could not fetch the workspace', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch` and look at what it says' })
   const available = snapshot.capabilities.includes('change-requests')
   // Knowledge bases whose documents come too: opt-in, as for a pull (`*` for every one the project has).
-  const asked = (flagString(ctx, 'documents') ?? '').split(',').map((s) => s.trim().replace(/^knowledge\//, '')).filter(Boolean)
-  const knowledgeHere = [...projectRefs(project.root).values()].filter((r) => r.kind === 'knowledge').map((r) => r.name)
-  const documentNames = asked.includes('*') ? knowledgeHere : asked
-  const notHere = documentNames.filter((n) => !knowledgeHere.includes(n))
-  if (notHere.length) throw new UsageError(`no knowledge base ${notHere.join(', ')} in this project`, '--documents takes knowledge base names (knowledge/<name>), or * for every one')
+  // Agent knowledge by name (`knowledge/<name>`), a Knowledge app base by its folder (`knowledge-base/<folder>`).
+  const asked = (flagString(ctx, 'documents') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+  const here = [...projectRefs(project.root).values()]
+  const knowledgeHere = here.filter((r) => r.kind === 'knowledge').map((r) => r.name)
+  const basesHere = here.filter((r) => r.kind === 'knowledge-base' && `${KNOWLEDGE_BASE_DIR}/${r.name}` !== KNOWLEDGE_SETTINGS_REF).map((r) => `${KNOWLEDGE_BASE_DIR}/${r.name}`)
+  const isBase = (a: string) => a.startsWith(`${KNOWLEDGE_BASE_DIR}/`)
+  const documentNames = asked.includes('*') ? knowledgeHere : asked.filter((a) => !isBase(a)).map((a) => a.replace(/^knowledge\//, ''))
+  const documentBases = asked.includes('*') ? basesHere : asked.filter(isBase)
+  const notHere = [...documentNames.filter((n) => !knowledgeHere.includes(n)), ...documentBases.filter((r) => !basesHere.includes(r))]
+  if (notHere.length) throw new UsageError(`no knowledge base ${notHere.join(', ')} in this project`, '--documents takes knowledge base names (knowledge/<name>, or knowledge-base/<folder> for the Knowledge app), or * for every one')
   const api = await platformFor(target)
-  const documents = documentNames.length
-    ? { names: new Set(documentNames), pulled: readPulledDocuments(target.state, link.workspace).bases, platform: await platformDocuments(api, documentNames, remote.items) }
+  // The Knowledge app's bases are read, proposed and applied as the person signed in, never with the project's keys.
+  const signedIn = here.some((r) => r.kind === 'knowledge-base') || plan.some((p) => p.kind === 'knowledge-base') ? await personReader(target.owner, link) : null
+  const documents = documentNames.length || documentBases.length
+    ? {
+        names: new Set([...documentNames, ...documentBases]),
+        pulled: readPulledDocuments(target.state, link.workspace).bases,
+        platform: new Map([...(await platformDocuments(api, documentNames, remote.items)), ...(await baseDocumentsOn(signedIn, documentBases, remote.items))]),
+      }
     : undefined
   const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, named, ...(documents ? { documents } : {}) })
+  if (!signedIn) {
+    const signIn = signInCommand(api.acting.profile)
+    for (const i of all) {
+      if (i.kind !== 'knowledge-base' || !i.proposable) continue
+      Object.assign(i, { proposable: false, blocked: 'sign-in', reason: `This workspace’s knowledge bases need a sign-in: run \`${signIn}\`, then push again`, fix: `sign in with \`${signIn}\`` })
+    }
+  }
   // A named target is never pulled from: what it changed since this project delivered it has its own words.
   const changedThere = target.name ? plan.filter((p) => p.status === 'changed').map((p) => ({ ref: p.ref, kind: p.kind, title: p.title })) : []
   if (target.name) {
@@ -764,7 +823,8 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   const known = snapshot.names?.model ? new Set(Object.keys(snapshot.names.model)) : null
   const missing = known ? markMissingModels(all, known) : new Map<string, string[]>()
   const checked = available ? await precheck(api, all, organizationKeyOf(api.acting), target) : { checked: false, refused: [] as string[], plan: [] as ApplyStep[] }
-  const person = needsAPerson(checked.plan)
+  // Sources the project's Knowledge settings keep off: the platform's checks pass them, and Apply refuses them.
+  const person = [...personNeeds(checked.plan, api.acting), ...sourcesOffNeeds(project.root).filter((n) => all.some((i) => i.ref === n.ref && i.proposable))]
   const kept = currentRequest(readRequests(target.state, link.workspace))
   const updating = kept && isOpen(kept.state) ? kept : null
   const orgStored = !!getSyncKey(target.owner, 'organization')
@@ -835,7 +895,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   // Named items must each be proposable; with none named, an item the workspace moved past stops the push.
   const stopping = chosen.filter((i) => !i.proposable && (named.length > 0 || i.blocked === 'moved' || i.blocked === 'conflicts'))
   if (stopping.length) {
-    const lines = stopping.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)
+    const lines = stopping.map((i) => `  ${labelOf(i)}: ${i.reason}`)
     throw new CliError(`not proposed: ${plural(stopping.length, 'item')} cannot go yet\n${lines.join('\n')}`, {
       code: 'SYNC_PUSH_BLOCKED',
       hint: target.name && stopping.some((i) => i.blocked === 'moved')
@@ -852,7 +912,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     // Changes the checks refused are changes still: say why each can't go, not that nothing changed.
     const held = chosen.filter((i) => !i.proposable && !i.sample)
     if (held.length) {
-      throw new CliError(`nothing to propose: ${plural(held.length, 'change')} here cannot go yet\n${held.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]).join('\n')}`, {
+      throw new CliError(`nothing to propose: ${plural(held.length, 'change')} here cannot go yet\n${held.flatMap((i) => [`  ${labelOf(i)}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]).join('\n')}`, {
         code: 'SYNC_PUSH_BLOCKED',
         hint: `fix ${held.length === 1 ? 'it' : 'them'} as said, then check with \`${command('push --preview')}\``,
         details: { blocked: held.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })) },
@@ -916,16 +976,18 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })),
       samples: leftSamples.map((i) => i.ref),
       ...stewardData(api.acting, needsOrganizationKey(view.items), orgStored),
+      needsPerson: person.filter((p) => going.some((i) => i.ref === p.ref)),
       notCarried,
     },
     text: [
       `${open ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${targetLabel(target)}: ${plural(view.items.length, 'item')}.`,
       ...going.map((i) => `  ${pushItemLine(i)}`),
       ...releases.map((r) => `  Custom App ${r.slug}: release ${r.deployment}${r.chosen ? ' (its newest deployment)' : ''}; Apply promotes it last`),
-      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
+      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${labelOf(i)}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
       ...changedThereLines(target, changedThere),
       ...(leftSamples.length ? ['', `Left out: ${plural(leftSamples.length, 'sample')} from setting up the project (${leftSamples.map((i) => i.title).join(', ')}); name ${leftSamples.length === 1 ? 'it' : 'them'} to propose`] : []),
       ...(needsOrganizationKey(view.items) ? ['', stewardNote(api.acting, true, pushAgain(api.acting, view))] : []),
+      ...needLines(person.filter((p) => going.some((i) => i.ref === p.ref))),
       ...(mcp ? ['', mcp.line] : []),
       '',
       `Apply it with \`${command('request apply')}\`; see it with \`${command('request')}\`.`,
@@ -1072,6 +1134,18 @@ async function currentView(target: SyncTarget): Promise<{ view: View; titles: Re
  * request proposed before items were named by display name kept "brand"),
  * then what its proposed files declare. The kept titles are not rewritten.
  */
+/** Whether an Agent's file sets its knowledge bases, which Apply sets as the person applying. */
+function picksIn(text: string | undefined): boolean {
+  try {
+    return Array.isArray((JSON.parse(text ?? '') as { knowledgeBases?: unknown }).knowledgeBases)
+  } catch {
+    return false
+  }
+}
+
+/** Each item's title by ref, as the request's lines name them. */
+const allTitlesOf = (view: View, titles: Record<string, string>) => Object.fromEntries(view.items.map((i) => [i.ref, titleOf(i, titles)]))
+
 function titleOf(item: ViewItem, titles: Record<string, string>): string {
   if (item.kind === 'app') return `${item.name} ${releasedDeployment(item) ?? ''}`.trim()
   return itemTitle(item.kind, item.name, item.files, titles[item.ref])
@@ -1178,17 +1252,28 @@ async function apply(ctx: CommandContext) {
   if (view.request.state === 'merged') throw new CliError(`“${view.request.title}” is already applied`, { code: 'CONFLICT', hint: `propose new changes with \`${command('push -t "<title>"')}\`` })
   if (view.request.state === 'closed') throw new CliError(`“${view.request.title}” is closed`, { code: 'CONFLICT', hint: `propose the changes again with \`${command('push -t "<title>"')}\`` })
   const proposed: ProposedBy = proposedByOther(acting, view) === 'key' ? 'key' : 'you'
-  if (acting.as === 'person' && acting.organizationKeyStored && view.items.some((i) => i.kind === 'blueprint' || i.kind === 'agent')) {
+  const stewardMatters = acting.as === 'person' && acting.organizationKeyStored && view.items.some((i) => i.kind === 'blueprint' || i.kind === 'agent')
+  // A knowledge base, the Knowledge settings and an Agent's picks are applied by a person who may change them.
+  const knowledgeMatters = view.items.some((i) => i.kind === 'knowledge-base' || (i.kind === 'agent' && picksIn(i.files[`agents/${i.name}/agent.json`])))
+  if (stewardMatters || knowledgeMatters) {
     // The platform refuses a person who is no Steward only once Apply runs, so ask its checks, with every item so references resolve.
-    const items = view.items.map((i) => ({ ref: i.ref, files: i.files, ...(i.baseRevision ? { baseRevision: i.baseRevision } : {}), ...(i.deleted ? { deleted: true } : {}) }))
+    const items = view.items.map((i) => ({ ref: i.ref, ...(i.resourceId && i.kind === 'knowledge-base' ? { id: i.resourceId } : {}), files: i.files, ...(i.baseRevision ? { baseRevision: i.baseRevision } : {}), ...(i.deleted ? { deleted: true } : {}) }))
     const plan = await api.call<unknown>('POST', '/v1/change-requests/check', { items }, { timeoutMs: 120_000 }).then(planOf, () => [])
-    const stop = notSteward(acting, stewardStepUnmet(needsAPerson(plan), view.items), pushAgain(acting, view), proposed)
+    const stop = stewardMatters ? notSteward(acting, stewardStepUnmet(needsAPerson(plan), view.items), pushAgain(acting, view), proposed) : null
     if (stop) throw stop
+    const unmet = personNeeds(plan, acting).filter((n) => n.code.startsWith('knowledge_') && !n.after)
+    if (unmet.length) {
+      throw new CliError(`not applied: ${unmet.map((n) => `${allTitlesOf(view, titles)[n.ref] ?? n.ref}: ${n.message}`).join('; ')}`, {
+        code: unmet.some((n) => n.code === 'knowledge_needs_person') ? 'SYNC_NOT_SIGNED_IN' : 'FORBIDDEN',
+        hint: unmet[0]!.fix,
+        details: { needsPerson: unmet },
+      })
+    }
   }
   const refused = notProposer(acting, view, 'apply')
   // A workspace admin signed in may apply another's request once every item is approved: the platform decides.
   if (refused && !(acting.as === 'person' && view.request.state === 'approved')) throw refused
-  const allTitles = Object.fromEntries(view.items.map((i) => [i.ref, titleOf(i, titles)]))
+  const allTitles = allTitlesOf(view, titles)
   const blueprint = view.items.some((i) => i.kind === 'blueprint')
   // With the keys, sent whenever one is stored: an Agent's Blueprint grants are a Steward's too, in a request without Blueprint files (P5 A5).
   const organizationKey = organizationKeyOf(acting)
@@ -1243,7 +1328,9 @@ async function apply(ctx: CommandContext) {
   try {
     // A deletion shows only in a full read of the workspace's index (an incremental one lists no deletions).
     const deleted = answer.items.filter((i) => i.deleted).map((i) => i.ref)
-    const result = await fetchTarget(project, target, { full: deleted.length > 0 })
+    // A knowledge base keeps the folder it was proposed from, whatever name the workspace files it under (one just created too).
+    const folders = new Map(answer.items.flatMap((i) => (i.kind === 'knowledge-base' && i.resourceId && !i.deleted && i.ref !== KNOWLEDGE_SETTINGS_REF ? [[i.resourceId, i.name] as const] : [])))
+    const result = await fetchTarget(project, target, { full: deleted.length > 0, knowledgeBaseFolders: folders })
     // A Custom App release moved a pointer; the App's own sync item (its description) is not the project's to adopt.
     const adoptable = answer.items.filter((i) => i.kind !== 'app').map((i) => i.ref)
     // A named target's base is its own (`target.state`), so the next push to it reads what changed there since.
@@ -1295,6 +1382,7 @@ async function apply(ctx: CommandContext) {
  */
 async function recordAppliedDocuments(target: SyncTarget, api: Platform, view: View): Promise<void> {
   const { link } = target
+  await recordAppliedBaseDocuments(target, view)
   const items = view.items.filter((i) => i.kind === 'knowledge' && i.documents)
   if (!items.length) return
   const snapshot = readSnapshot(target.state)
@@ -1322,6 +1410,24 @@ async function recordAppliedDocuments(target: SyncTarget, api: Platform, view: V
   }
 }
 
+/** The same for the Knowledge app's bases, read as the person signed in, recorded under `knowledge-base/<folder>`. */
+async function recordAppliedBaseDocuments(target: SyncTarget, view: View): Promise<void> {
+  const items = view.items.filter((i) => i.kind === 'knowledge-base' && i.documents && i.resourceId)
+  if (!items.length) return
+  const person = await personReader(target.owner, target.link)
+  if (!person) return
+  for (const item of items) {
+    const rows = await knowledgeBaseDocumentsOn(person.workspace, item.resourceId!)
+    const entries: Record<string, PulledDocument | null> = {}
+    for (const d of item.documents!.upload) {
+      const newest = rows.filter((r) => r.fileName === d.fileName && !r.synced).sort((a, b) => String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? '')))[0]
+      if (newest) entries[d.fileName] = { sourceId: newest.id, sha256: d.sha256, bytes: d.bytes, at: new Date().toISOString() }
+    }
+    for (const d of item.documents!.remove) entries[d.fileName] = null
+    recordPulledDocuments(target.state, target.link.workspace, item.ref, entries)
+  }
+}
+
 async function close(ctx: CommandContext) {
   const project = localProject(ctx.cwd)
   const target = chooseTarget(project, ctx)