@frontera-sdk/cli 1.53.23 → 1.53.24

package/src/local/local-knowledge-base-sources-off.ts

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_FILE, KNOWLEDGE_BASE_SETTINGS_FILE, KNOWLEDGE_BASE_SOURCES_DIR, type KnowledgeBaseFile, type KnowledgeBaseSettingsFile, type KnowledgeSourcePolicy } from './local-knowledge-base-files'
+
+/** What Apply on the platform would refuse, said before anything is sent, in the shape of the platform's person needs. */
+export interface SourcesOffNeed {
+  step: string
+  ref: string
+  code: 'knowledge_sources_off'
+  message: string
+  fix: string
+}
+
+const SETTINGS = `${KNOWLEDGE_BASE_DIR}/${KNOWLEDGE_BASE_SETTINGS_FILE}`
+
+function readJson<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T
+  } catch {
+    return null
+  }
+}
+
+/** Whether the policy lets a base of this scope have sources, as the platform decides it. */
+function allows(policy: KnowledgeSourcePolicy, scope: KnowledgeBaseFile['scope']): boolean {
+  if (policy.apiSources === 'off') return false
+  if (policy.apiSources === 'organization') return scope === 'organization'
+  // shortcut: chosen_workspaces names slugs and the link keeps the workspace's id, so it is taken as allowing; read the slug if this misleads.
+  return true
+}
+
+/**
+ * Each knowledge base with files in `sources/` whose sources the project's
+ * Knowledge settings (`knowledge-base/settings.json`) keep off for it, or,
+ * with no `sources` in that file, whose sources Apply needs allowed: a new
+ * workspace keeps API sources off, and Apply refuses such a base.
+ */
+export function sourcesOffNeeds(root: string): SourcesOffNeed[] {
+  const dir = join(root, KNOWLEDGE_BASE_DIR)
+  if (!existsSync(dir)) return []
+  const policy = readJson<KnowledgeBaseSettingsFile>(join(dir, KNOWLEDGE_BASE_SETTINGS_FILE))?.sources
+  const needs: SourcesOffNeed[] = []
+  for (const folder of readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort()) {
+    const base = readJson<KnowledgeBaseFile>(join(dir, folder, KNOWLEDGE_BASE_FILE))
+    if (!base) continue
+    const sourcesDir = join(dir, folder, KNOWLEDGE_BASE_SOURCES_DIR)
+    const sources = existsSync(sourcesDir) ? readdirSync(sourcesDir).filter((f) => f.endsWith('.json')).sort() : []
+    if (!sources.length || (policy && allows(policy, base.scope))) continue
+    const place = base.scope === 'organization' ? 'organization knowledge bases' : 'this workspace'
+    const files = sources.map((f) => `${KNOWLEDGE_BASE_SOURCES_DIR}/${f}`).join(', ')
+    const why = policy
+      ? `${SETTINGS} keeps API sources ${policy.apiSources === 'off' ? 'off' : 'to organization knowledge bases'}`
+      : null
+    needs.push({
+      step: `Knowledge base ${base.name ?? folder}`,
+      ref: `${KNOWLEDGE_BASE_DIR}/${folder}`,
+      code: 'knowledge_sources_off',
+      // Without pulled settings the platform's policy is unknown here: most people cannot read it, so say what Apply depends on.
+      message: why
+        ? `Its sources (${files}) need API sources allowed for ${place}, and ${why}, so Apply would refuse it`
+        : `Its sources (${files}) need API sources allowed for ${place}. This project has no Knowledge settings to check that against, so Apply refuses it if the workspace keeps API sources off, as a new workspace does`,
+      fix: `set "sources": {"apiSources": "${base.scope === 'organization' ? 'organization' : 'all_workspaces'}"} in ${SETTINGS} and propose it with the base (an organization owner or admin applies it), or leave the source out`,
+    })
+  }
+  return needs
+}

package/src/local/local-person-steps.ts

@@ -28,7 +28,7 @@ import { projectTargets, targetOf, targetProfileName } from './local-sync-link'
 export const PERSON_STEPS_FILE = join('.frontera', 'sync', 'person-steps.json')
 
 /** Who or what the step needs. */
-export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person', 'registry-owner'] as const
+export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'knowledge-steward', 'admin', 'second-person', 'person', 'registry-owner'] as const
 export type Credential = (typeof CREDENTIALS)[number]
 
 /** Each credential in the person's words, as the card and the list say it. */
@@ -36,6 +36,7 @@ export const CREDENTIAL_WORDS: Record<Credential, string> = {
   'workspace-key': 'the project’s workspace key',
   'organization-key': 'an organization key',
   steward: 'a Blueprint Steward',
+  'knowledge-steward': 'a Knowledge steward',
   admin: 'a workspace admin',
   'second-person': 'a second person (not whoever made the change)',
   person: 'you, signed in (`frontera auth login --browser`)',

package/src/local/local-personas.ts

@@ -5,6 +5,7 @@ import { parse as parseYaml } from 'yaml'
 
 import { CliError, UsageError } from '../errors'
 import { isIgnoredName } from './local-dev-sync'
+import { KNOWLEDGE_BASE_DIR } from './local-knowledge-base-files'
 import { localRuntimeAt } from './local-runtime-target'
 import type { LocalCredentials } from './local-state'
 
@@ -20,7 +21,8 @@ import type { LocalCredentials } from './local-state'
  * The submitter is an `owner` (an Action grants its invoke capability to
  * owners only); approvers are `admin`s. `frontera action available|submit|approve|reject --as
  * <persona>` then runs as that persona, and so do `media list|upload|stage` (both roles hold
- * Media content write, so a persona can stage the file an attachment Action takes). The session it uses is minted for the
+ * Media content write, so a persona can stage the file an attachment Action takes). A project with
+ * knowledge bases also gets the `KNOWLEDGE_PERSONAS`, which `frontera knowledge-base` reads as. The session it uses is minted for the
  * one command, sent only to the local runtime, and never printed or logged.
  */
 
@@ -32,8 +34,22 @@ export const ACT_AS_COMMANDS = [
   'action available', 'action submit', 'action approve', 'action reject',
   // L6: a persona's files, into the runtime's stand-in Media Sets, and staged for an Action to attach.
   'media list', 'media upload', 'media stage',
+  // Who reads which knowledge base: the steward, a member of the workspace and someone outside it.
+  'knowledge-base list', 'knowledge-base status', 'knowledge-base search', 'knowledge-base documents',
 ] as const
 
+/**
+ * The people a project with knowledge bases tests access with: a Knowledge
+ * steward (manages organization bases), a member of the workspace (reads its
+ * bases and those shared with it) and an outsider, a member of the
+ * organization in no workspace here, who reads none of them.
+ */
+export const KNOWLEDGE_PERSONAS: readonly PersonaSpec[] = [
+  { key: 'knowledge-steward', displayName: 'Knowledge steward', orgRole: 'editor', knowledgeSteward: true, decides: ['organization knowledge bases, as a Knowledge steward'] },
+  { key: 'workspace-member', displayName: 'Workspace member', orgRole: 'viewer', decides: ['reading this workspace\'s knowledge bases'] },
+  { key: 'outsider', displayName: 'Outsider', orgRole: 'viewer', inWorkspace: false, decides: ['nothing: in the organization, in no workspace here'] },
+]
+
 const KEY = /^[a-z][a-z0-9_-]{0,62}$/
 /** The most personas one seed takes (the route's limit). */
 const MAX_PERSONAS = 20
@@ -51,7 +67,11 @@ export interface PersonaSpec {
    * The organization role it holds: `owner` for the submitter (an Action
    * grants its invoke capability to owners only), `admin` for an approver.
    */
-  orgRole: 'owner' | 'admin'
+  orgRole: 'owner' | 'admin' | 'editor' | 'viewer'
+  /** `false`: a member of the organization only, in no workspace here. */
+  inWorkspace?: false
+  /** Made a Knowledge steward after it is seeded, with the owner's session. */
+  knowledgeSteward?: true
   /** What the persona is for, in words: "decides step dispatch_lead of escalateWorkOrder". */
   decides: string[]
 }
@@ -128,8 +148,9 @@ export function personaPlan(root: string): PersonaPlan {
     const names = actionDocs(root).map(({ file, doc }) => (typeof doc.apiName === 'string' ? doc.apiName : file))
     add(SUBMITTER, names.length ? `requests for ${names.join(', ')}` : 'requests, as the person who submits them')
   }
-  // The submitter first, then the approvers as their steps come.
+  // The submitter first, then the approvers as their steps come, then the knowledge personas.
   const personas = [...byKey.values()].sort((a, b) => Number(b.key === SUBMITTER) - Number(a.key === SUBMITTER))
+  if (existsSync(join(root, KNOWLEDGE_BASE_DIR))) personas.push(...KNOWLEDGE_PERSONAS.filter((p) => !byKey.has(p.key)).map((p) => ({ ...p, decides: [...p.decides] })))
   if (personas.length > MAX_PERSONAS) notes.push(`${personas.length - MAX_PERSONAS} more approval steps than the ${MAX_PERSONAS} personas a runtime seeds at once: the rest were left out`)
   return { personas: personas.slice(0, MAX_PERSONAS), notes }
 }
@@ -199,15 +220,48 @@ export async function seedPersonas(root: string, serviceUrl: string, creds: Loca
   if (!plan.personas.length) return lines
   let answer: { status: number; body: unknown }
   try {
-    answer = await personaCall(serviceUrl, creds, fetcher)('POST', '/', { personas: plan.personas.map((p) => ({ key: p.key, displayName: p.displayName, orgRole: p.orgRole })) })
+    answer = await personaCall(serviceUrl, creds, fetcher)('POST', '/', { personas: plan.personas.map((p) => ({ key: p.key, displayName: p.displayName, orgRole: p.orgRole, ...(p.inWorkspace === false ? { inWorkspace: false } : {}) })) })
   } catch (err) {
     return [...lines, `  note: local personas could not be seeded: ${(err as Error).message}`]
   }
   if (answer.status === 404) return [...lines, '  note: this runtime has no local personas (its platform predates them), so approval chains can only be decided by a person here']
   if (answer.status >= 300) return [...lines, `  note: local personas could not be seeded: ${messageOf(answer)}`]
   const keys = plan.personas.map((p) => p.key)
-  const approver = keys.find((k) => k !== SUBMITTER)
-  return [...lines, `  local personas ${keys.join(', ')}: act as one with \`--as\`${approver ? ` (\`frontera action approve <requestId> --as ${approver}\`)` : ''}`]
+  const approver = keys.find((k) => k !== SUBMITTER && !KNOWLEDGE_PERSONAS.some((p) => p.key === k))
+  const stewards = plan.personas.filter((p) => p.knowledgeSteward).map((p) => p.key)
+  const stewardLines = stewards.length ? await assignStewards(serviceUrl, creds, stewards, answer.body, fetcher) : []
+  const knowledge = keys.includes('outsider') ? ' (`frontera knowledge-base search "<words>" --as outsider`)' : ''
+  return [...lines, ...stewardLines, `  local personas ${keys.join(', ')}: act as one with \`--as\`${approver ? ` (\`frontera action approve <requestId> --as ${approver}\`)` : knowledge}`]
+}
+
+/**
+ * Make the seeded personas `keys` Knowledge stewards, with the owner's
+ * session: the Knowledge app takes no organization key. Notes only, never a
+ * failure; the route assigns a steward again without change.
+ */
+async function assignStewards(serviceUrl: string, creds: LocalCredentials, keys: string[], seeded: unknown, fetcher: Fetch): Promise<string[]> {
+  const data = inner(seeded)
+  const rows = (isRecord(data) && Array.isArray(data.personas) ? data.personas : []).filter(isRecord)
+  const notes: string[] = []
+  for (const key of keys) {
+    const userId = rows.find((p) => p.key === key)?.userId
+    if (!creds.session || typeof userId !== 'string') {
+      notes.push(`  note: ${key} could not be made a Knowledge steward: ${creds.session ? 'the runtime did not name it' : 'the runtime has no owner session; restart it'}`)
+      continue
+    }
+    try {
+      const res = await fetcher(new URL('/v1/knowledge-app/stewards', serviceUrl), {
+        method: 'POST',
+        headers: { authorization: `Bearer ${creds.session}`, 'x-org-id': creds.organizationId, 'content-type': 'application/json' },
+        body: JSON.stringify({ userId }),
+      })
+      if (res.status === 404) notes.push(`  note: ${key} is not a Knowledge steward: this runtime does not run the Knowledge app (\`frontera local start --with search-index\`)`)
+      else if (res.status >= 300) notes.push(`  note: ${key} could not be made a Knowledge steward: ${messageOf({ status: res.status, body: await res.json().catch(() => null) })}`)
+    } catch (err) {
+      notes.push(`  note: ${key} could not be made a Knowledge steward: ${(err as Error).message}`)
+    }
+  }
+  return notes
 }
 
 export interface PersonaSession {
@@ -251,7 +305,7 @@ export async function actAsLocalPersona(opts: {
     throw new CliError(known ? `no local persona is named ${key}` : 'this runtime has no local personas', {
       code: 'PERSONA_NOT_FOUND',
       hint: known
-        ? `${known.length ? `the personas here are ${known.map((p) => p.key).join(', ')}; ` : ''}\`frontera local dev\` seeds one per approval step in blueprint/actions/, plus ${SUBMITTER}`
+        ? `${known.length ? `the personas here are ${known.map((p) => p.key).join(', ')}; ` : ''}\`frontera local dev\` seeds one per approval step in blueprint/actions/, plus ${SUBMITTER}, and ${KNOWLEDGE_PERSONAS.map((p) => p.key).join(', ')} for a project with knowledge-base/`
         : 'its platform predates them: start the runtime from a release that has them (`frontera local start`)',
     })
   }
@@ -298,6 +352,9 @@ export function localPersonaHint(meta: { noun: string; verb: string }, personas:
   const approver = approvers[0] ?? 'approver'
   const listed = personas?.length ? `the personas here are ${personas.map((p) => p.key).join(', ')}` : '`frontera local status` lists the personas (Personas)'
   const never = 'never a person’s session token'
+  if (meta.noun === 'knowledge-base' && (ACT_AS_COMMANDS as readonly string[]).includes(label)) {
+    return `on this local runtime, act as a local persona: ${KNOWLEDGE_PERSONAS.map((p) => `\`--as ${p.key}\``).join(', ')} (\`frontera ${label} --as outsider\`); ${listed}: ${never}`
+  }
   if (!(ACT_AS_COMMANDS as readonly string[]).includes(label)) {
     return `on this local runtime no person signs in, and \`--as <persona>\` acts as a local persona only on ${ACT_AS_COMMANDS.map((c) => `\`${c}\``).join(', ')}; \`${label}\` runs against a deployment, where a person signs in (${never} here)`
   }

package/src/local/local-portability.ts

@@ -3,6 +3,7 @@ import { posix } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
 import { actionSemanticConflicts, type SemanticFacts } from '../blueprint/action-semantic-fit'
+import { KNOWLEDGE_BASE_FILE, KNOWLEDGE_BASE_SOURCES_DIR, type KnowledgeBaseFile, type KnowledgeBaseSourceFile } from './local-knowledge-base-files'
 import { unnamedObjectBindings } from './local-objects'
 import { governedActionIds, referencesIn } from './local-sync-refs'
 
@@ -101,6 +102,10 @@ export type Need =
    * index from before this read the same Action as `action-refused`.)
    */
   | { kind: 'action-inherited'; reasons: string[] }
+  /** A knowledge base's source that signs in (`credentialSecret`): here with the secret set on the runtime, on the platform with a credential entered on the base's page. */
+  | { kind: 'source-credential'; source: string; secret: string }
+  /** An organization knowledge base shared with chosen workspaces: here, with the runtime's one workspace. */
+  | { kind: 'shared-workspaces'; workspaces: string[] }
 
 export interface Portability {
   class: PortabilityClass
@@ -172,6 +177,10 @@ export function judge(need: Need, ctx: Context = {}): { class: PortabilityClass;
       return { class: 'adapted', text: `goes without ${need.count === 1 ? 'one of its object tools' : `${need.count} of its object tools`} here: the pull couldn’t read ${need.count === 1 ? 'its object definition' : 'their object definitions'} on the platform` }
     case 'context-unread':
       return { class: 'adapted', text: 'its Context and data couldn’t be read on the platform: read access to the pulled object types is assumed here until it can be read' }
+    case 'source-credential':
+      return { class: 'adapted', text: `its source ${need.source} signs in here with the secret ${need.secret} set on this runtime; on the platform, its credential is entered on the knowledge base’s page` }
+    case 'shared-workspaces':
+      return { class: 'adapted', text: `shared with ${listed(need.workspaces)} on the platform; here, with this runtime’s one workspace, the project’s` }
   }
 }
 
@@ -415,7 +424,25 @@ function parse(path: string, text: string): unknown {
 /** What a built-in Plugin is, when it is not a connection to another system. */
 export type BuiltInKind = 'documentation' | 'analytics'
 
+/** What a knowledge base's files need: its sharing with chosen workspaces, and each source that signs in. */
+export function knowledgeBaseNeeds(base: KnowledgeBaseFile, sources: ReadonlyArray<{ stem: string; spec: { credentialSecret?: string } }>): Need[] {
+  const needs: Need[] = []
+  if (base.scope === 'organization' && base.sharing && 'workspaces' in base.sharing) needs.push({ kind: 'shared-workspaces', workspaces: base.sharing.workspaces })
+  for (const s of sources) if (s.spec.credentialSecret) needs.push({ kind: 'source-credential', source: s.stem, secret: s.spec.credentialSecret })
+  return needs
+}
+
 export function itemNeeds(kind: string, files: Record<string, string>, connections: ReadonlySet<string> = new Set(), builtIns: ReadonlyMap<string, BuiltInKind> = new Map()): Need[] {
+  if (kind === 'knowledge-base') {
+    const base = Object.entries(files).find(([path]) => path.endsWith(`/${KNOWLEDGE_BASE_FILE}`))
+    const doc = base ? (parse(base[0], base[1]) as KnowledgeBaseFile | null) : null
+    const sources = Object.entries(files).flatMap(([path, text]) => {
+      if (!new RegExp(`/${KNOWLEDGE_BASE_SOURCES_DIR}/[^/]+\\.json$`).test(path)) return []
+      const spec = parse(path, text) as KnowledgeBaseSourceFile | null
+      return spec ? [{ stem: posix.basename(path, '.json'), spec }] : []
+    })
+    return doc && typeof doc === 'object' ? knowledgeBaseNeeds(doc, sources) : []
+  }
   const needs: Need[] = []
   const actions = new Set<string>()
   const plugins = new Set<string>()

package/src/local/local-ports.ts

@@ -20,14 +20,15 @@ import { removeRuntimeResources } from './local-docker'
  * one, for every project whose folder is gone.
  */
 
-export type PortName = 'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces'
+export type PortName = 'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces' | 'search-index'
 
 export type PortBlock = Record<PortName, number>
 
 const BASE = 54100
 const BLOCK = 10
 const MAX_BLOCKS = 40
-const OFFSETS: Record<PortName, number> = { studio: 0, service: 1, jobs: 2, runner: 3, postgres: 4, cache: 5, embeddings: 6, storage: 7, traces: 8 }
+// The block is full: another port would change BLOCK, and with it every project's ports.
+const OFFSETS: Record<PortName, number> = { studio: 0, service: 1, jobs: 2, runner: 3, postgres: 4, cache: 5, embeddings: 6, storage: 7, traces: 8, 'search-index': 9 }
 
 interface Registry {
   version: 1
@@ -59,6 +60,7 @@ function blockFrom(start: number): PortBlock {
     embeddings: start + OFFSETS.embeddings,
     storage: start + OFFSETS.storage,
     traces: start + OFFSETS.traces,
+    'search-index': start + OFFSETS['search-index'],
   }
 }
 

package/src/local/local-project-secrets.ts

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 import { parse as parseYaml } from 'yaml'
 
 import { allTargets } from './local-dev-sync'
+import { KNOWLEDGE_BASE_SOURCES_DIR } from './local-knowledge-base-files'
 import { functionSecretNames, hasSecretValue, type SecretPresence, workflowSecretNames } from './local-secrets'
 
 /**
@@ -67,14 +68,38 @@ export function readProjectSecrets(root: string): ProjectSecrets | null {
   return { secrets, problems }
 }
 
+/** The secret each source of a Knowledge app base signs in with (`credentialSecret`), with its file. */
+function sourceSecrets(root: string, baseFile: string): Array<[string, string]> {
+  const dir = join(dirname(baseFile), KNOWLEDGE_BASE_SOURCES_DIR)
+  let names: string[] = []
+  try {
+    names = readdirSync(join(root, dir)).filter((n) => n.endsWith('.json')).sort()
+  } catch {
+    return []
+  }
+  return names.flatMap((n): Array<[string, string]> => {
+    try {
+      const secret = (JSON.parse(readFileSync(join(root, dir, n), 'utf8')) as { credentialSecret?: unknown }).credentialSecret
+      return typeof secret === 'string' && secret ? [[secret, join(dir, n)]] : []
+    } catch {
+      return []
+    }
+  })
+}
+
 /**
- * The secret names the project's Functions and workflows name in their files,
- * each with the first file that names it: a Function's `secret:NAME` grants
- * (a single-file Function, or a folder's entry) and a workflow's `auth`.
+ * The secret names the project's Functions, workflows and knowledge base
+ * sources name in their files, each with the first file that names it: a
+ * Function's `secret:NAME` grants (a single-file Function, or a folder's
+ * entry), a workflow's `auth` and a source's `credentialSecret`.
  */
 export function secretsNamedInFiles(root: string): Map<string, string> {
   const out = new Map<string, string>()
   for (const target of allTargets(root)) {
+    if (target.kind === 'knowledge-base') {
+      for (const [name, file] of sourceSecrets(root, target.file)) if (!out.has(name)) out.set(name, file)
+      continue
+    }
     if (target.kind !== 'function' && target.kind !== 'workflow') continue
     let names: string[] = []
     try {

package/src/local/local-scaffold.ts

@@ -582,6 +582,8 @@ const GITIGNORE = `node_modules/
 .env
 # A separate browser plugin's output (screenshots of other sites included); the frontera browser keeps its own under .frontera/.
 .playwright-mcp/
+# Knowledge base documents: brought on request, often the customer's own content.
+knowledge-base/*/documents/
 `
 
 /**

package/src/local/local-schema-check.ts

@@ -7,7 +7,7 @@
  * Only the keywords this CLI's own schemas use (`local-schemas.ts`,
  * `local-blueprint-schemas.ts`): type, enum, const, required, properties,
  * additionalProperties, items, the length and count bounds, pattern,
- * minimum/maximum, anyOf, oneOf and allOf. A keyword it does not know is not
+ * minimum/maximum, anyOf, oneOf, allOf and not. A keyword it does not know is not
  * checked, so a schema is never stricter here than it says.
  */
 
@@ -118,6 +118,8 @@ export function checkAgainstSchema(value: unknown, schema: Schema, path = ''): S
     }
   }
 
+  // `{ not: {} }` matches nothing: on a property, the key must be absent.
+  if (isRecord(schema.not) && checkAgainstSchema(value, schema.not, path).length === 0) say(Object.keys(schema.not).length ? 'is not allowed here' : 'must be left out')
   for (const sub of Array.isArray(schema.allOf) ? schema.allOf : []) if (isRecord(sub)) out.push(...checkAgainstSchema(value, sub, path))
   if (Array.isArray(schema.anyOf) && schema.anyOf.length) {
     const results = schema.anyOf.map((b) => (isRecord(b) ? checkAgainstSchema(value, b, path) : []))

package/src/local/local-schemas.ts

@@ -7,6 +7,7 @@ import type { LocalProject } from './local-project'
 import { isAlive, readState } from './local-state'
 import { PROCEDURE_TOOL_FORMS, PROCEDURE_TOOL_GROUPS } from './local-agent-checks'
 import { DEFAULT_HANDOVER_REASON_KEYS } from './local-operating'
+import { KNOWLEDGE_BASE_SCHEMA, KNOWLEDGE_BASE_SETTINGS_SCHEMA, KNOWLEDGE_BASES_FIELD } from './local-knowledge-base-files'
 import { TARGET_NAME } from './local-sync-link'
 import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
 
@@ -14,7 +15,7 @@ import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
  * The formats of a project's files, as JSON Schema, for the coding agents and
  * editors working in it (`frontera local schema <kind>`).
  *
- * The service checks four of them (an Agent, its behavior, a workflow, an MCP server), so their schemas come from the service
+ * The service checks five of them (an Agent, its behavior, a workflow, an MCP server, a knowledge base source), so their schemas come from the service
  * the runtime runs (`GET /v1/config/file-schemas/<kind>`), made from the same
  * zod schemas that check the files, then widened where a project file names a
  * resource by reference instead of id (`localizeServiceSchema`). The others
@@ -38,6 +39,9 @@ export const SCHEMA_KINDS = [
   'app',
   'mcp-server',
   'knowledge',
+  'knowledge-base',
+  'knowledge-base-source',
+  'knowledge-base-settings',
   'skill',
   'blueprint-object-type',
   'blueprint-link-type',
@@ -66,6 +70,9 @@ export const SCHEMA_FILES: Record<SchemaKind, string> = {
   app: 'apps/<slug>.json',
   'mcp-server': 'mcp-servers/<slug>.yaml',
   knowledge: 'knowledge/<name>/knowledge.json',
+  'knowledge-base': 'knowledge-base/<name>/knowledge-base.json',
+  'knowledge-base-source': 'knowledge-base/<name>/sources/<source>.json',
+  'knowledge-base-settings': 'knowledge-base/settings.json',
   skill: 'skills/<name>/SKILL.md (its front matter)',
   secrets: 'secrets.json',
   sync: 'frontera.yaml (its sync block)',
@@ -826,6 +833,8 @@ export function cliSchema(kind: SchemaKind): JsonSchema | null {
   if (kind === 'chat-app') return CHAT_APP_SCHEMA
   if (kind === 'app') return APP_SCHEMA
   if (kind === 'knowledge') return KNOWLEDGE_SCHEMA
+  if (kind === 'knowledge-base') return KNOWLEDGE_BASE_SCHEMA
+  if (kind === 'knowledge-base-settings') return KNOWLEDGE_BASE_SETTINGS_SCHEMA
   if (kind === 'skill') return SKILL_SCHEMA
   if (kind === 'secrets') return SECRETS_SCHEMA
   if (kind === 'sync') return SYNC_SCHEMA
@@ -967,6 +976,7 @@ function describeProjectFields(props: Record<string, unknown>): void {
         required: ['knowledgeConfigId'],
       },
     })
+    if (!('knowledgeBases' in props)) props.knowledgeBases = KNOWLEDGE_BASES_FIELD
     describe(props, 'objectBindings', 'Object definitions (the workspace’s objects, not Blueprint object types) the Agent reads and writes through its object tools: each row `objectDefinitionId: object/<slug>` with its `definition` (name, fields). The Blueprint object types it may query are granted in agents/<slug>/bindings.json `blueprint`, not here.')
     describe(props, 'functions', 'Not applied: these rows are no longer run. The Functions and workflows the Agent may start are its bindings, in agents/<slug>/bindings.json (`frontera local schema bindings`).')
     // `config.features`: the Agent's own Computer availability, kept beside the on/off switches (the service's `computer-runtime-policy.ts`).

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

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { searchIndexVolumeName, type DockerRunSpec } from './local-docker'
+
+/**
+ * The local runtime's search index: one OpenSearch node per project, for the
+ * Knowledge app's knowledge bases. It runs only for a project that builds
+ * knowledge bases (`knowledge-base/`) or when asked (`--with search-index`),
+ * because it adds about 1 GB of memory to the runtime.
+ */
+
+/** The engine the platform's compose file and chart run. */
+export const SEARCH_INDEX_IMAGE = 'opensearchproject/opensearch:3.8.0'
+
+/**
+ * Docker memory below which it stays off. Its own cap is 1.5 GiB: the JVM uses
+ * about 850 MiB beside a 512 MB heap when idle. With the runtime's other
+ * containers that comes to about 5.3 GB. Docker Desktop reports about 97% of
+ * its Memory limit (8092 MiB read as 7851 MiB), so a 6 GB limit reads about
+ * 5.8 GiB: the check takes 5.5 GiB, and the message names the limit to set.
+ */
+const MIN_DOCKER_MEMORY = 5.5 * 1024 ** 3
+
+export type SearchIndexChoice = { on: true } | { on: false; why: string }
+
+export function searchIndexChoice(input: { root: string; with: readonly string[]; exclude: readonly string[]; dockerMemoryBytes: number | null }): SearchIndexChoice {
+  if (input.exclude.includes('search-index')) return { on: false, why: 'excluded' }
+  if (!input.with.includes('search-index') && !existsSync(join(input.root, 'knowledge-base'))) {
+    return { on: false, why: 'no knowledge-base/ folder in the project; `frontera local start --with search-index` starts it' }
+  }
+  if (input.dockerMemoryBytes !== null && input.dockerMemoryBytes < MIN_DOCKER_MEMORY) {
+    const has = (input.dockerMemoryBytes / 1024 ** 3).toFixed(1)
+    return {
+      on: false,
+      why: `Docker has ${has} GB of memory, and the search index needs more: in Docker Desktop, set Settings > Resources > Memory limit to 6 GB or more, then run \`frontera local start\` again`,
+    }
+  }
+  return { on: true }
+}
+
+/** Uploaded files go to object storage and are read by the jobs engine's workers. */
+export function searchIndexNeeds(exclude: readonly string[]): string | null {
+  const missing = exclude.filter((name) => name === 'storage' || name === 'jobs')
+  if (!missing.length) return null
+  return `the search index needs storage and jobs: drop \`--exclude ${missing.join(',')}\`, or add \`--exclude search-index\``
+}
+
+export function searchIndexRunSpec(args: { name: string; projectId: string; port: number }): DockerRunSpec {
+  return {
+    name: args.name,
+    image: SEARCH_INDEX_IMAGE,
+    projectId: args.projectId,
+    // Only the REST port: the performance analyzer's 9600 stays inside the container.
+    ports: [{ host: args.port, container: 9200 }],
+    env: {
+      'discovery.type': 'single-node',
+      // It listens on loopback only, as the platform's compose file runs it for development.
+      DISABLE_SECURITY_PLUGIN: 'true',
+      DISABLE_INSTALL_DEMO_CONFIG: 'true',
+      OPENSEARCH_JAVA_OPTS: '-Xms512m -Xmx512m',
+    },
+    volumes: [{ name: searchIndexVolumeName(args.projectId), path: '/usr/share/opensearch/data' }],
+    memory: '1536m',
+    cpus: '1',
+    flags: ['--ulimit', 'nofile=65536:65536'],
+  }
+}
+
+/** Null when the search index answers with a usable cluster (a single node is yellow), else why not. */
+export async function searchIndexHealth(port: number, timeoutMs = 1500): Promise<string | null> {
+  let res: Response
+  try {
+    res = await fetch(`http://127.0.0.1:${port}/_cluster/health`, { signal: AbortSignal.timeout(timeoutMs) })
+  } catch {
+    return `nothing answers on its port ${port}`
+  }
+  if (!res.ok) return `its cluster health answered ${res.status}`
+  const status = ((await res.json().catch(() => null)) as { status?: string } | null)?.status
+  return status === 'green' || status === 'yellow' ? null : `its cluster health is ${status ?? 'unreadable'}`
+}
+
+/** Waits for a usable cluster; the last reason when it never came. */
+export async function waitForSearchIndex(port: number, timeoutMs: number): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs
+  let why = await searchIndexHealth(port)
+  while (why && Date.now() < deadline) {
+    await Bun.sleep(1000)
+    why = await searchIndexHealth(port)
+  }
+  return why
+}

package/src/local/local-secrets.ts

@@ -129,6 +129,8 @@ export async function missingSecretLines(names: string[], who: string, serviceUr
 export interface SecretPresence {
   names: Set<string>
   withoutValue: Set<string>
+  /** When each listed secret was last set, as the route says; what a source's credential is sent again after. */
+  updatedAt?: Map<string, string>
 }
 
 /** Whether the runtime has a value for `name`: listed, and not said to be without one. */
@@ -145,16 +147,19 @@ export async function localSecretPresence(serviceUrl: string, creds: LocalCreden
       signal: AbortSignal.timeout(5000),
     })
     if (!res.ok) return null
-    const body = (await res.json()) as { data?: Array<{ name?: string; hasValue?: unknown }> } | Array<{ name?: string; hasValue?: unknown }>
+    type Row = { name?: string; hasValue?: unknown; updatedAt?: unknown }
+    const body = (await res.json()) as { data?: Row[] } | Row[]
     const rows = Array.isArray(body) ? body : (body.data ?? [])
     const names = new Set<string>()
     const withoutValue = new Set<string>()
+    const updatedAt = new Map<string, string>()
     for (const r of rows) {
       if (typeof r.name !== 'string') continue
       names.add(r.name)
       if (r.hasValue === false) withoutValue.add(r.name)
+      if (typeof r.updatedAt === 'string') updatedAt.set(r.name, r.updatedAt)
     }
-    return { names, withoutValue }
+    return { names, withoutValue, updatedAt }
   } catch {
     return null
   }

package/src/local/local-seed.ts

@@ -380,6 +380,23 @@ export async function ensureProviderModels(args: { serviceUrl: string; password:
   return added
 }
 
+/**
+ * With the search index on, the seeded owner is a Knowledge steward, so
+ * organization knowledge bases can be created and shared here. Assigning one
+ * again does nothing, so every start asks; a refusal is logged, never fatal.
+ */
+export async function ensureKnowledgeSteward(args: { serviceUrl: string; password: string; organizationId: string; logFile: string }): Promise<void> {
+  const signedIn = await call<{ token?: string; user?: { id?: string } }>(args.serviceUrl, '/api/auth/sign-in/email', { body: { email: OWNER_EMAIL, password: args.password } })
+  const token = signedIn.body?.token ?? signedIn.headers.get('set-auth-token')
+  const userId = signedIn.body?.user?.id
+  if (signedIn.status !== 200 || !token || !userId) {
+    log(args.logFile, `could not sign in to make the owner a Knowledge steward (${signedIn.status})`)
+    return
+  }
+  const assigned = await call(args.serviceUrl, '/v1/knowledge-app/stewards', { token, orgId: args.organizationId, body: { userId } })
+  if (assigned.status >= 300) log(args.logFile, `making the owner a Knowledge steward answered ${assigned.status}: ${JSON.stringify(assigned.body).slice(0, 200)}`)
+}
+
 /**
  * Make Blueprint usable in a fresh local organization: the lifecycle
  * adopted, so the Blueprint CLI loop (`pull`, `plan`, `apply`) and Studio's Blueprint section

package/src/local/local-state.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import { ignoreInFronteraDir } from '../project-context'
 import { writeFileAtomic } from '../fs-atomic'
+import type { PortBlock } from './local-ports'
 import type { LocalProject } from './local-project'
 
 /**
@@ -14,7 +15,10 @@ import type { LocalProject } from './local-project'
  * same file, and the supervisor's pid in it says whether anyone is home.
  */
 
-export type ComponentName = 'postgres' | 'storage' | 'service' | 'jobs' | 'runner' | 'studio'
+/** Every component, in the order the supervisor starts them and `local status` lists them. */
+export const COMPONENTS = ['postgres', 'storage', 'search-index', 'service', 'jobs', 'runner', 'studio'] as const
+
+export type ComponentName = (typeof COMPONENTS)[number]
 
 export type ComponentStatus = 'off' | 'starting' | 'running' | 'stopped' | 'failed'
 
@@ -63,7 +67,7 @@ export interface LocalState {
   error?: string
   startedAt: string
   updatedAt: string
-  ports: Record<'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces', number>
+  ports: PortBlock
   components: ComponentState[]
   credentials?: LocalCredentials
 }
@@ -113,10 +117,8 @@ export function updateComponent(state: LocalState, next: ComponentState): LocalS
   return { ...state, components: [...others, next].sort(byOrder) }
 }
 
-const ORDER: ComponentName[] = ['postgres', 'storage', 'service', 'jobs', 'runner', 'studio']
-
 function byOrder(a: ComponentState, b: ComponentState): number {
-  return ORDER.indexOf(a.name) - ORDER.indexOf(b.name)
+  return COMPONENTS.indexOf(a.name) - COMPONENTS.indexOf(b.name)
 }
 
 /** Whether a pid names a live process. Signal 0 checks without delivering anything. */