@frontera-sdk/cli 1.53.22 → 1.53.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.22",
+  "version": "1.53.24",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.22",
-    "@frontera-sdk/functions": "1.53.22",
+    "@frontera-sdk/core": "1.53.24",
+    "@frontera-sdk/functions": "1.53.24",
     "ai": "^6.0.319",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.22",
+    "@frontera-sdk/forge-contracts": "1.53.24",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/knowledge-base-api.ts

@@ -0,0 +1,230 @@
+import { CliError } from '../errors'
+import { organizationHeaders } from '../organization'
+import { credentialFailure } from './credential-failure'
+import { formatValidationDetails } from './validation-detail'
+
+/**
+ * The Knowledge app's knowledge bases (`/v1/knowledge-app`), for `frontera
+ * knowledge-base` and the `knowledge_base_*` MCP tools. Not Agent knowledge,
+ * which `PlatformApi.knowledgeBases` reads.
+ *
+ * Every call acts as a person: the person's own session on a platform, the
+ * runtime's owner (or a local persona, with `--as`) on the local runtime. The
+ * app refuses organization keys on the whole prefix, and a workspace key needs
+ * the Knowledge purpose, which a project's key does not have.
+ */
+
+export interface KnowledgeBase {
+  id: string
+  name: string
+  description: string | null
+  ownerWorkspaceId: string | null
+  canManage: boolean
+  sharing: { allWorkspaces: boolean; workspaceIds: string[] } | null
+}
+
+export interface KnowledgeDocument {
+  id: string
+  title: string
+  fileName: string | null
+  status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+  searchable: boolean
+  error: string | null
+  source: { id: string; name: string; url: string | null } | null
+  updatedAt: string
+}
+
+export interface KnowledgeSearchResult {
+  documentId: string
+  title: string
+  knowledgeBase: { id: string; name: string } | null
+  page: number | null
+  snippet: string
+  score: number
+  openUrl: string
+  fileName: string | null
+}
+
+export interface KnowledgeSource {
+  id: string
+  knowledgeBaseId: string
+  kind: string
+  name: string
+  host: string
+  state: string
+  documents: number
+  canManage: boolean
+  sync: { nextAt?: string | null; failures?: number; lastFailure?: { message?: string } | null } & Record<string, unknown>
+  /** Present only for whoever manages the base. */
+  schedule?: unknown
+  keepRemovedDays?: unknown
+  config?: unknown
+  auth?: { kind: string } & Record<string, unknown>
+}
+
+export interface KnowledgeSteward {
+  userId: string
+  email: string | null
+  displayName: string | null
+  role: string
+}
+
+/** A base's documents by where they are: `reading` is scanning, waiting or being read; `failed` includes blocked files. */
+export interface BaseStatus {
+  base: KnowledgeBase
+  scope: 'workspace' | 'organization'
+  documents: number
+  ready: number
+  reading: number
+  failed: number
+}
+
+/** What a refusal says next, by where the command runs. */
+export const KNOWLEDGE_OFF_NEXT = {
+  local: 'start the local runtime with its search index: `frontera local stop`, then `frontera local start --with search-index` (a project with a knowledge-base/ folder starts it by itself)',
+  platform: 'Ask your administrator to turn on the Knowledge app.',
+} as const
+
+export class KnowledgeBaseApi {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly token: string,
+    /** Sent as `x-workspace-id`: where the person stands, which decides the bases they read. */
+    private readonly workspaceId: string | undefined,
+    /** Whether `apiUrl` is the project's local runtime: it decides what a refusal tells the reader to do. */
+    private readonly local: boolean,
+    /** Sent as `x-org-id` when given; else the organization the command selected. */
+    private readonly orgId?: string,
+  ) {}
+
+  private orgHeaders(): Record<string, string> {
+    return this.orgId ? { 'x-org-id': this.orgId } : organizationHeaders()
+  }
+
+  private async call<T>(path: string, options: { method?: string; body?: unknown } = {}): Promise<T> {
+    const response = await fetch(`${this.apiUrl.replace(/\/+$/, '')}/v1/knowledge-app${path}`, {
+      method: options.method ?? 'GET',
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        ...this.orgHeaders(),
+        ...(this.workspaceId ? { 'x-workspace-id': this.workspaceId } : {}),
+        ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+    })
+    const text = await response.text()
+    let payload: { data?: unknown; message?: string; code?: string; details?: { reason?: string } & Record<string, unknown> } | null
+    try {
+      payload = text ? JSON.parse(text) : null
+    } catch {
+      payload = null
+    }
+    if (response.ok) return (payload?.data ?? payload) as T
+
+    // `knowledge_off`, or no reason at all: a release that does not mount the app.
+    const reason = payload?.details?.reason
+    if (response.status === 404 && (reason === 'knowledge_off' || reason === undefined)) {
+      throw new CliError(this.local ? 'this local runtime does not run the Knowledge app' : 'this platform does not run the Knowledge app', {
+        code: 'KNOWLEDGE_OFF',
+        hint: this.local ? KNOWLEDGE_OFF_NEXT.local : KNOWLEDGE_OFF_NEXT.platform,
+      })
+    }
+    const credential = credentialFailure(response.status, payload?.message, { token: this.token, code: payload?.code, details: payload?.details })
+    if (credential) throw credential
+    const detail = formatValidationDetails(payload?.details)
+    throw new CliError(payload?.message ?? `Request failed (${response.status}).`, {
+      code: payload?.code ?? 'FAILURE',
+      ...(detail ? { hint: detail } : {}),
+    })
+  }
+
+  async bases(): Promise<KnowledgeBase[]> {
+    return (await this.call<{ bases: KnowledgeBase[] }>('/bases')).bases
+  }
+
+  /** One page of a base's documents, newest first, and how many match in all. */
+  documents(baseId: string, query: { status?: KnowledgeDocument['status']; limit?: number; cursor?: string } = {}): Promise<{ documents: KnowledgeDocument[]; nextCursor: string | null; total: number }> {
+    const params = new URLSearchParams()
+    for (const [k, v] of Object.entries(query)) if (v !== undefined) params.set(k, String(v))
+    const qs = params.toString()
+    return this.call(`/bases/${encodeURIComponent(baseId)}/documents${qs ? `?${qs}` : ''}`)
+  }
+
+  /** Every document of a base, page after page. */
+  async allDocuments(baseId: string): Promise<KnowledgeDocument[]> {
+    const all: KnowledgeDocument[] = []
+    let cursor: string | undefined
+    do {
+      const page = await this.documents(baseId, { limit: 200, ...(cursor ? { cursor } : {}) })
+      all.push(...page.documents)
+      cursor = page.nextCursor ?? undefined
+    } while (cursor)
+    return all
+  }
+
+  /** The ready, reading and failed counts of each base: four counts a base, asked at once. */
+  async statuses(bases: KnowledgeBase[]): Promise<BaseStatus[]> {
+    const count = async (id: string, status?: KnowledgeDocument['status']) => (await this.documents(id, { limit: 1, ...(status ? { status } : {}) })).total
+    return Promise.all(bases.map(async (base) => {
+      const [documents, ready, failed, blocked] = await Promise.all([count(base.id), count(base.id, 'ready'), count(base.id, 'failed'), count(base.id, 'blocked')])
+      return { base, scope: scopeOf(base), documents, ready, reading: Math.max(0, documents - ready - failed - blocked), failed: failed + blocked }
+    }))
+  }
+
+  async search(body: { query: string; knowledgeBaseIds?: string[]; limit?: number }): Promise<{ results: KnowledgeSearchResult[]; total: number; mode: string; correctedQuery?: string }> {
+    return this.call('/search', { method: 'POST', body })
+  }
+
+  async sources(baseId: string): Promise<KnowledgeSource[]> {
+    return (await this.call<{ sources: KnowledgeSource[] }>(`/bases/${encodeURIComponent(baseId)}/sources`)).sources
+  }
+
+  /** Test connection: the first page of a source as it would be added. Stores nothing. */
+  async testSource(baseId: string, spec: Record<string, unknown>): Promise<unknown> {
+    return (await this.call<{ test: unknown }>(`/bases/${encodeURIComponent(baseId)}/sources/test`, { method: 'POST', body: spec })).test
+  }
+
+  async syncSource(sourceId: string): Promise<KnowledgeSource> {
+    return (await this.call<{ source: KnowledgeSource }>(`/sources/${encodeURIComponent(sourceId)}/sync`, { method: 'POST' })).source
+  }
+
+  async stewards(): Promise<KnowledgeSteward[]> {
+    return (await this.call<{ stewards: KnowledgeSteward[] }>('/stewards')).stewards
+  }
+
+  async addSteward(userId: string): Promise<void> {
+    await this.call('/stewards', { method: 'POST', body: { userId } })
+  }
+
+  async removeSteward(userId: string): Promise<void> {
+    await this.call(`/stewards/${encodeURIComponent(userId)}`, { method: 'DELETE' })
+  }
+
+  /** The organization member with this email, from the members list any member reads. */
+  async memberByEmail(email: string): Promise<{ userId: string; email: string } | null> {
+    const response = await fetch(`${this.apiUrl.replace(/\/+$/, '')}/v1/users/members?limit=100&search=${encodeURIComponent(email)}`, {
+      headers: { Authorization: `Bearer ${this.token}`, ...this.orgHeaders() },
+    })
+    const payload = (await response.json().catch(() => null)) as { data?: { data?: Array<{ userId: string; user?: { email?: string | null } }> }; message?: string } | null
+    if (!response.ok) {
+      throw credentialFailure(response.status, payload?.message, { token: this.token }) ?? new CliError(payload?.message ?? `Request failed (${response.status}).`, { code: 'FAILURE', hint: 'pass the person’s user id instead of the email' })
+    }
+    const match = (payload?.data?.data ?? []).find((m) => (m.user?.email ?? '').toLowerCase() === email.toLowerCase())
+    return match ? { userId: match.userId, email: match.user!.email! } : null
+  }
+}
+
+export function scopeOf(base: Pick<KnowledgeBase, 'ownerWorkspaceId'>): 'workspace' | 'organization' {
+  return base.ownerWorkspaceId ? 'workspace' : 'organization'
+}
+
+/** A result as a reader cites it: `title (base, page 3)`. */
+export function citation(result: Pick<KnowledgeSearchResult, 'title' | 'knowledgeBase' | 'page'>): string {
+  const where = [result.knowledgeBase?.name, result.page ? `page ${result.page}` : null].filter(Boolean).join(', ')
+  return where ? `${result.title} (${where})` : result.title
+}
+
+/** The snippet without the search's `<mark>` around the query's words. */
+export function plainSnippet(snippet: string): string {
+  return snippet.replace(/<\/?mark>/g, '').replace(/\s+/g, ' ').trim()
+}

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

@@ -28,15 +28,15 @@ interface KnowledgeRow {
 
 /**
  * These commands manage the knowledge bases Agents attach. The Knowledge app's
- * bases (organization and workspace) are another thing with no command or
- * project file, and no local runtime runs the app. Said only where the
- * platform runs the app: elsewhere there is no such base to mistake for one.
+ * bases (organization and workspace) are another kind, with their own command
+ * and project folder. Said only where the platform runs the app: elsewhere
+ * there is no such base to mistake for one.
  */
 async function knowledgeAppNote(api: PlatformApi): Promise<string> {
   return (await api.knowledgeAppRuns())
-    ? ' A knowledge base from the Knowledge app is not one of these: it runs on the platform only, with its search and AI answers, not on a local runtime. '
-      + 'Choose it for an Agent on the platform, under the Agent\'s Knowledge page, and test that Agent there. '
-      + 'Its sources, the other systems it copies documents from, are added on the platform too, on the knowledge base\'s page.'
+    ? ' A knowledge base from the Knowledge app is not one of these: use `frontera knowledge-base` for it. '
+      + 'A project holds it in knowledge-base/<name>/, brought with `frontera local sync pull --kinds knowledge-bases`, '
+      + 'and an Agent searches it once its agent.json lists `knowledge-base/<name>` in knowledgeBases.'
     : ''
 }
 

package/src/commands/knowledge-base/index-commands.ts

@@ -0,0 +1,328 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  citation,
+  KnowledgeBaseApi,
+  plainSnippet,
+  scopeOf,
+  type KnowledgeBase,
+  type KnowledgeSource,
+} from '../../api/knowledge-base-api'
+import { CliError, UsageError } from '../../errors'
+import { KNOWLEDGE_BASE_DIR, KNOWLEDGE_BASE_FILE } from '../../local/local-knowledge-base-files'
+import { platformRefName } from '../../local/local-knowledge-base-pull'
+import { KNOWLEDGE_PERSONAS } from '../../local/local-personas'
+import { localProject } from '../../local/local-project'
+import { localRuntimeAt } from '../../local/local-runtime-target'
+import { readSecretValue } from '../../secrets'
+import { table } from '../../table'
+import { flagString, flagStrings, type Command, type CommandContext, type CommandMeta } from '../types'
+
+/**
+ * `frontera knowledge-base`: the Knowledge app's knowledge bases (folder
+ * `knowledge-base/<name>/` in a project), on the local runtime or a platform.
+ * Not `frontera knowledge`, which is Agent knowledge.
+ *
+ * Every verb acts as a person, because the Knowledge app takes no
+ * organization key and a project's workspace key lacks its purpose: the
+ * runtime's owner on the local runtime (`localOwner`), a local persona with
+ * `--as`, and the person signed in (`frontera auth login --browser`) on a
+ * platform.
+ */
+
+const SESSION: Pick<CommandMeta, 'authLane' | 'localOwner' | 'sessionAlternative'> = {
+  authLane: 'session',
+  localOwner: true,
+  sessionAlternative: 'the Knowledge app on the platform',
+}
+
+const PERSONA_KEYS = KNOWLEDGE_PERSONAS.map((p) => p.key).join(', ')
+
+function api(ctx: CommandContext): KnowledgeBaseApi {
+  return new KnowledgeBaseApi(ctx.apiUrl, ctx.token, ctx.workspaceId, !!localRuntimeAt(ctx.cwd, ctx.apiUrl))
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** The name a project folder's base has: `name` in its knowledge-base.json, else the folder's. */
+function folderBaseName(cwd: string, folder: string): string | null {
+  let root: string
+  try {
+    root = localProject(cwd).root
+  } catch {
+    return null
+  }
+  const file = join(root, KNOWLEDGE_BASE_DIR, folder, KNOWLEDGE_BASE_FILE)
+  if (!existsSync(file)) return null
+  try {
+    const name = (JSON.parse(readFileSync(file, 'utf8')) as { name?: unknown }).name
+    return typeof name === 'string' && name.trim() ? name.trim() : folder
+  } catch {
+    return folder
+  }
+}
+
+/** A base the person reads, by id, by name, or by its project folder (`knowledge-base/<folder>` or `<folder>`). */
+export async function resolveBase(client: KnowledgeBaseApi, cwd: string, ref: string): Promise<KnowledgeBase> {
+  const bases = await client.bases()
+  if (UUID.test(ref)) {
+    const byId = bases.find((b) => b.id.toLowerCase() === ref.toLowerCase())
+    if (byId) return byId
+  }
+  const folder = ref.replace(new RegExp(`^${KNOWLEDGE_BASE_DIR}/`), '').replace(/\/+$/, '')
+  const wanted = [ref, folderBaseName(cwd, folder)].filter((n): n is string => !!n).map((n) => n.toLowerCase())
+  const named = bases.filter((b) => wanted.includes(b.name.toLowerCase()))
+  if (named.length === 1) return named[0]!
+  if (named.length > 1) {
+    throw new CliError(`${named.length} knowledge bases are named "${named[0]!.name}"`, {
+      code: 'AMBIGUOUS',
+      hint: `pass one by id: ${named.map((b) => `${b.id} (${scopeOf(b)})`).join(', ')}`,
+    })
+  }
+  throw new CliError(`no knowledge base "${ref}" that you can read here`, {
+    code: 'NOT_FOUND',
+    hint: bases.length
+      ? `the bases you read here: ${bases.map((b) => b.name).join(', ')}`
+      : 'you read no knowledge base here: `frontera knowledge-base list` shows what you can read',
+  })
+}
+
+function sharingWords(base: KnowledgeBase): string {
+  if (!base.sharing) return ''
+  if (base.sharing.allWorkspaces) return 'all workspaces'
+  const n = base.sharing.workspaceIds.length
+  return n === 0 ? 'no workspace' : `${n} workspace${n === 1 ? '' : 's'}`
+}
+
+const list: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'list',
+    args: [],
+    flags: { as: 'string' },
+    summary: 'List the knowledge bases you can read here, the workspace’s and the organization’s shared with it',
+    details: [`On the local runtime the command acts as its owner; \`--as\` acts as a local persona (${PERSONA_KEYS}).`],
+    examples: ['frontera knowledge-base list', 'frontera knowledge-base list --as outsider --json'],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const bases = await api(ctx).bases()
+    return {
+      data: bases.map((b) => ({ ...b, scope: scopeOf(b) })),
+      text: bases.length === 0
+        ? 'No knowledge bases you can read here.'
+        : table(['name', 'scope', 'shared with', 'id'], bases.map((b) => [b.name, scopeOf(b), sharingWords(b), b.id]), [40, undefined, undefined, undefined]),
+    }
+  },
+}
+
+const status: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'status',
+    args: [{ name: 'base', required: false, description: 'one knowledge base, by name, id or project folder; all you read when absent' }],
+    flags: { as: 'string' },
+    summary: 'Show each knowledge base’s documents: ready, still reading, and failed',
+    details: ['Reading counts files being checked, waiting or being read. Failed counts files that could not be read and files the check blocked; `frontera knowledge-base documents <base>` names them.'],
+    examples: ['frontera knowledge-base status', 'frontera knowledge-base status policies --json'],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const client = api(ctx)
+    const ref = ctx.positional[0]
+    const bases = ref ? [await resolveBase(client, ctx.cwd, ref)] : await client.bases()
+    const rows = await client.statuses(bases)
+    return {
+      data: rows.map(({ base, ...counts }) => ({ id: base.id, name: base.name, ...counts })),
+      text: rows.length === 0
+        ? 'No knowledge bases you can read here.'
+        : table(['name', 'scope', 'ready', 'reading', 'failed'], rows.map((r) => [r.base.name, r.scope, String(r.ready), String(r.reading), String(r.failed)]), [40, undefined, undefined, undefined, undefined]),
+    }
+  },
+}
+
+const search: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'search',
+    args: [{ name: 'query', required: true, description: 'what to search for, as a person would ask it' }],
+    flags: { as: 'string', base: 'string', limit: 'string' },
+    summary: 'Search the knowledge bases you can read, and cite where each result comes from',
+    details: [
+      `It searches as the person it acts as, so it finds only what that person may read. On the local runtime, \`--as\` tests that: \`--as outsider\` finds nothing in the workspace’s bases. The personas are ${PERSONA_KEYS}.`,
+    ],
+    flagHelp: { base: 'search only this knowledge base, by name, id or project folder; repeat for more', limit: 'how many results to show (1 to 50, default 10)' },
+    examples: [
+      'frontera knowledge-base search "late repayment fee"',
+      'frontera knowledge-base search "late repayment fee" --base policies --limit 5',
+      'frontera knowledge-base search "late repayment fee" --as outsider',
+    ],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const query = ctx.positional.join(' ').trim()
+    if (!query) throw new UsageError('missing <query>', 'frontera knowledge-base search "what a person would ask"')
+    const limit = flagString(ctx, 'limit')
+    const n = limit === undefined ? 10 : Number(limit)
+    if (!Number.isInteger(n) || n < 1 || n > 50) throw new UsageError('--limit takes a whole number from 1 to 50', `frontera knowledge-base search "${query}" --limit 10`)
+    const client = api(ctx)
+    const only = await Promise.all(flagStrings(ctx, 'base').map((ref) => resolveBase(client, ctx.cwd, ref)))
+    const answer = await client.search({ query, limit: n, ...(only.length ? { knowledgeBaseIds: only.map((b) => b.id) } : {}) })
+    const results = answer.results.map((r, i) => ({ n: i + 1, citation: citation(r), ...r, snippet: plainSnippet(r.snippet) }))
+    const corrected = answer.correctedQuery ? `Searched for “${answer.correctedQuery}”.\n\n` : ''
+    return {
+      data: { query, results, total: answer.total, mode: answer.mode, ...(answer.correctedQuery ? { correctedQuery: answer.correctedQuery } : {}) },
+      text: results.length === 0
+        ? `No results for “${query}” in the knowledge bases you can read here.`
+        : corrected + results.map((r) => `[${r.n}] ${r.citation}\n    ${r.snippet}`).join('\n\n'),
+    }
+  },
+}
+
+const documents: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'documents',
+    args: [{ name: 'base', required: true, description: 'knowledge base by name, id or project folder' }],
+    flags: { as: 'string' },
+    summary: 'List one knowledge base’s documents and where each one stands',
+    examples: ['frontera knowledge-base documents policies', 'frontera knowledge-base documents policies --json'],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const ref = ctx.positional[0]
+    if (!ref) throw new UsageError('missing <base>', 'frontera knowledge-base list — then pass a name')
+    const client = api(ctx)
+    const base = await resolveBase(client, ctx.cwd, ref)
+    const docs = await client.allDocuments(base.id)
+    return {
+      data: docs,
+      text: docs.length === 0
+        ? `No documents in ${base.name}.`
+        : table(
+          ['title', 'status', 'from', 'id'],
+          docs.map((d) => [d.title, d.error ? `${d.status}: ${d.error}` : d.status, d.source?.name ?? 'uploaded', d.id]),
+          [50, 40, 24, undefined],
+        ),
+    }
+  },
+}
+
+/** A source by its id, its name, or its file name in the project (`sources/<name>.json`, as a pull names it). */
+function findSource(sources: KnowledgeSource[], ref: string, base: KnowledgeBase): KnowledgeSource {
+  const stem = ref.replace(/\.json$/, '')
+  const match = sources.find((s) => s.id === ref) ?? sources.find((s) => s.name.toLowerCase() === stem.toLowerCase() || platformRefName(s.name) === stem)
+  if (match) return match
+  throw new CliError(`no source "${ref}" in ${base.name}`, {
+    code: 'NOT_FOUND',
+    hint: sources.length ? `its sources: ${sources.map((s) => s.name).join(', ')}` : `${base.name} has no sources here`,
+  })
+}
+
+const source: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'source',
+    args: [
+      { name: 'action', required: true, description: 'test | sync' },
+      { name: 'base', required: true, description: 'knowledge base by name, id or project folder' },
+      { name: 'source', required: true, description: 'the source by name or id' },
+    ],
+    flags: { 'credential-from': 'string' },
+    flagHelp: { 'credential-from': 'test only: where to read the credential of a source that signs in: `-` for stdin, or a file path. Never an inline value' },
+    summary: 'Test a source’s connection, or sync it now',
+    details: [
+      'test reads the first page of the source as it is set up on the target, and stores nothing. The stored credential is never sent back, so a source that signs in is tested with its credential from --credential-from.',
+      'sync makes the source due now. It is refused while the source syncs, is paused, or waits for its credential.',
+    ],
+    examples: [
+      'frontera knowledge-base source test policies help-center',
+      'frontera knowledge-base source test policies tickets --credential-from -',
+      'frontera knowledge-base source sync policies help-center',
+    ],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const [action, baseRef, sourceRef] = ctx.positional
+    if (action !== 'test' && action !== 'sync') throw new UsageError(`unknown action "${action ?? ''}"`, 'frontera knowledge-base source test|sync <base> <source>')
+    if (!baseRef || !sourceRef) throw new UsageError('missing <base> or <source>', `frontera knowledge-base source ${action} <base> <source>`)
+    const client = api(ctx)
+    const base = await resolveBase(client, ctx.cwd, baseRef)
+    const found = findSource(await client.sources(base.id), sourceRef, base)
+
+    if (action === 'sync') {
+      const after = await client.syncSource(found.id)
+      return { data: after, text: `${found.name} syncs now (${after.state}). \`frontera knowledge-base status ${base.name}\` shows its documents as they are read.` }
+    }
+
+    if (!found.config || !found.auth) {
+      throw new CliError(`only whoever manages ${base.name} can test its sources`, { code: 'FORBIDDEN', hint: 'a Knowledge steward manages organization bases; a workspace member with Knowledge update manages the workspace’s' })
+    }
+    const from = flagString(ctx, 'credential-from')
+    const signsIn = found.auth.kind !== 'none'
+    if (signsIn && !from) {
+      throw new UsageError(`${found.name} signs in, and the stored credential is never sent back`, `pass its credential for this test: \`frontera knowledge-base source test ${baseRef} ${sourceRef} --credential-from -\``)
+    }
+    const credential = signsIn ? (await readSecretValue(from!)).replace(/\r?\n$/, '') : undefined
+    const spec = { kind: found.kind, name: found.name, schedule: found.schedule, keepRemovedDays: found.keepRemovedDays, config: found.config, auth: found.auth, ...(credential ? { credential } : {}) }
+    const test = await client.testSource(base.id, spec) as { connected: boolean; page?: { items: number; more: boolean }; problem?: { message: string }; unmapped?: { items: number } }
+    return {
+      data: test,
+      text: test.connected
+        ? `${found.name} answers: ${test.page?.items ?? 0} items on its first page${test.page?.more ? ', and more pages' : ''}${test.unmapped?.items ? `; ${test.unmapped.items} items have fields that did not map` : ''}.`
+        : `${found.name} did not connect: ${test.problem?.message ?? 'no reason given'}`,
+    }
+  },
+}
+
+const steward: Command = {
+  meta: {
+    noun: 'knowledge-base',
+    verb: 'steward',
+    args: [
+      { name: 'action', required: true, description: 'list | add | remove' },
+      { name: 'person', required: false, description: 'add and remove: the person’s email in the organization, or their user id' },
+    ],
+    flags: {},
+    scope: 'organization',
+    summary: 'List, add or remove the organization’s Knowledge stewards, who manage its organization knowledge bases',
+    details: [
+      'Stewards are people, so they live on the platform and never in project files. Adding or removing one needs an organization owner or admin. On the local runtime the owner is a steward already.',
+    ],
+    examples: [
+      'frontera knowledge-base steward list',
+      'frontera knowledge-base steward add rina@example.com',
+      'frontera knowledge-base steward remove rina@example.com',
+    ],
+    ...SESSION,
+  },
+  async run(ctx) {
+    const [action, person] = ctx.positional
+    if (action !== 'list' && action !== 'add' && action !== 'remove') throw new UsageError(`unknown action "${action ?? ''}"`, 'frontera knowledge-base steward list|add|remove [person]')
+    const client = api(ctx)
+    if (action === 'list') {
+      const stewards = await client.stewards()
+      return {
+        data: stewards,
+        text: stewards.length === 0
+          ? 'No Knowledge stewards. An owner or admin adds one: `frontera knowledge-base steward add <email>`.'
+          : table(['email', 'name', 'role'], stewards.map((s) => [s.email ?? s.userId, s.displayName ?? '', s.role])),
+      }
+    }
+    if (!person) throw new UsageError('missing <person>', `frontera knowledge-base steward ${action} <email>`)
+    const isEmail = person.includes('@')
+    if (action === 'add') {
+      const member = isEmail ? await client.memberByEmail(person) : { userId: person, email: person }
+      if (!member) throw new CliError(`no member of this organization has the email ${person}`, { code: 'NOT_FOUND', hint: 'a steward is a member of the organization first: an owner or admin adds them in Organization settings' })
+      await client.addSteward(member.userId)
+      return { data: { added: member }, text: `${member.email} is a Knowledge steward.` }
+    }
+    const current = (await client.stewards()).find((s) => (isEmail ? (s.email ?? '').toLowerCase() === person.toLowerCase() : s.userId === person))
+    if (!current) return { data: { removed: null }, text: `${person} is not a Knowledge steward.` }
+    await client.removeSteward(current.userId)
+    return { data: { removed: current }, text: `${current.email ?? current.userId} is no longer a Knowledge steward.` }
+  },
+}
+
+export const knowledgeBaseCommands: readonly Command[] = [list, status, search, documents, source, steward]

package/src/commands/local/check.ts

@@ -14,6 +14,7 @@ import { repullRefFor } from '../../local/local-app-code'
 import { customAppFolders } from '../../local/local-apps'
 import { endCheckBaseline, readBaseline, restoreBaseline, restoreCutOffCheck, saveBaseline } from '../../local/local-db-snapshot'
 import { localIngestApi, settleKnowledge, type KnowledgeSettle } from '../../local/local-knowledge-ingestion'
+import { sourcesOffNeeds } from '../../local/local-knowledge-base-sources-off'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { projectSecretLines } from '../../local/local-project-secrets'
 import { localSecretPresence } from '../../local/local-secrets'
@@ -299,6 +300,11 @@ export function appsWithCheck(root: string): string[] {
   return customAppFolders(root).filter((dir) => !!readPackage(join(root, dir))?.scripts?.check)
 }
 
+/** Each knowledge base whose sources the project's Knowledge settings keep off, as `local check` warns of it. */
+export function sourcesOffWarnings(root: string): string[] {
+  return sourcesOffNeeds(root).map((n) => `${n.step}: ${n.message}. Fix: ${n.fix}`)
+}
+
 function parseSkip(raw: string | undefined): Set<CheckStepName> {
   const names = (raw ?? '').split(',').map((s) => s.trim()).filter(Boolean)
   for (const n of names) {
@@ -384,6 +390,12 @@ async function check(ctx: CommandContext) {
     record({ step, status: code === 0 ? 'passed' : 'failed', command: shown, ms: Date.now() - started, ...(code === 0 ? {} : { note: `\`${shown}\` exited ${code}` }) })
   }
 
+  // Said first, as a warning that fails nothing: the local runtime goes without such a source, and the platform's Apply refuses the base.
+  for (const line of sourcesOffWarnings(root)) {
+    ctx.output.note(`warning: ${line}`)
+    knowledgeNotes.push(line)
+  }
+
   for (const step of CHECK_STEPS) {
     const blocked = blockedBy(step, failedSteps, failFast)
     if (blocked) {