@agent-native/core 0.131.5 → 0.131.7

package/corpus/templates/brain/.agents/skills/brain/RUNBOOK.md

@@ -295,12 +295,13 @@ Clips, or external workspace data.
 ## Generic ingest payload validation
 
 The signed ingest webhook at `/api/_agent-native/brain/ingest` accepts a
-`RawCapturePayload`. Create a source with a `sourceKey` to receive a bearer
-token, set `Authorization: Bearer <ingestToken>` on the request, and send the
-payload shape below. Clips can export to that endpoint without Brain reading the
-Clips database directly. Generic sources use the same payload shape for call
-transcripts, customer research, imported notes, or any other source that can
-produce a bounded capture.
+normalized capture envelope. Create a source with a `sourceKey` to receive a
+bearer token, set `Authorization: Bearer <ingestToken>` on the request, and
+send one of the payload shapes below. Clips can export to that endpoint without
+Brain reading the Clips database directly. Generic sources use the same
+contract for call transcripts, customer research, approved FAQs/docs, imported
+notes, or any other source that can produce a bounded capture. Successful
+creates and updates automatically create or reuse a distillation queue item.
 
 ```json
 {
@@ -315,3 +316,50 @@ produce a bounded capture.
   "raw": {}
 }
 ```
+
+For a blessed document publisher, create a generic source with an explicit
+answer policy:
+
+```bash
+pnpm --filter brain action create-source \
+  --title "Blessed Agent Native docs" \
+  --provider generic \
+  --sourceKey agent-native-docs \
+  --policy '{"trustTier":"blessed","answerEligible":true,"authority":100,"freshnessWindowDays":null,"reviewRequired":false,"conflictBehavior":"prefer-higher-authority"}' \
+  --visibility org
+```
+
+Then publish one stable upstream record per `externalId`:
+
+```json
+{
+  "sourceKey": "agent-native-docs",
+  "externalId": "what-is-agent-native",
+  "title": "What is Agent Native?",
+  "kind": "document",
+  "content": "Agent Native is ...",
+  "capturedAt": "2026-07-30T12:00:00.000Z",
+  "sourceUrl": "https://docs.example.com/what-is-agent-native",
+  "tags": ["faq", "agent-native"],
+  "metadata": {
+    "slug": "what-is-agent-native",
+    "owner": "product"
+  }
+}
+```
+
+Reusing the same `sourceKey` and `externalId` updates the capture and
+invalidates its derived knowledge/search artifacts before re-distillation.
+When the upstream record is deleted or unblessed, send a content-free
+tombstone:
+
+```json
+{
+  "sourceKey": "agent-native-docs",
+  "externalId": "what-is-agent-native",
+  "deleted": true
+}
+```
+
+Tombstones retire the capture, remove its derived knowledge and published
+canonical resource, and prevent a stale retry from silently recreating it.

package/corpus/templates/brain/.agents/skills/brain/SKILL.md

@@ -10,12 +10,13 @@ Use Brain actions rather than raw SQL.
 1. Call `get-brain-settings` before answering, searching broadly, or distilling when current settings are not already in context. Apply the returned guidance for assistant name, company name, tone, source policy, citation requirements, publish tier, redaction, and distillation instructions.
 2. Import raw material with `import-capture` (generic) or `import-transcript`
    (meeting-shaped: participants, `sourceUrl`, tags). Both default
-   `enqueueDistillation: true` and auto-create a `manual` source when
-   `sourceId` is omitted — don't call `create-source` first just to import one
-   ad hoc capture.
-3. Call `enqueue-distillation` when a capture needs distillation. Re-running it
-   for a capture that's already queued/processing refreshes the handoff
-   instructions instead of creating a duplicate queue row.
+   `enqueueDistillation: true`, immediately create or reuse a queue item, and
+   auto-create a `manual` source when `sourceId` is omitted — don't call
+   `create-source` first just to import one ad hoc capture.
+3. Call `enqueue-distillation` when an existing capture needs an explicit
+   queue/retry handoff. Re-running it for a capture that's already
+   queued/processing refreshes the handoff instructions instead of creating a
+   duplicate queue row.
 4. Before writing knowledge, call `get-capture` and copy short exact quotes.
    Quotes and offsets always reference the persisted safe capture, never an
    upstream raw payload. `get-capture` redacts `title`/`content`/`metadata` by
@@ -131,13 +132,23 @@ not just documented:
 returning an answer with no usable citation — it returns a policy-explanation
 message instead of a bare summary when that happens.
 
+Each source may also carry an `answerPolicy`, configured through the
+`create-source` / `update-source` `policy` argument. `ask-brain` excludes stale
+or answer-ineligible results, prevents review-required raw captures from
+supporting answers, ranks `blessed` before `standard` before `untrusted`, and
+then ranks by `authority`. It returns the evaluated policy alongside citations
+so external apps can explain why a result was preferred or excluded. Sources
+without this policy retain the compatible `standard`, eligible, authority-50
+behavior.
+
 ## Publish Tiers And Proposal Gating
 
 `write-knowledge` writes at a `publishTier`: `private` (draft, private
 visibility), `team`, or `company` (published, org visibility) — default comes
 from `settings.defaultPublishTier`. A `company`-tier write becomes a
-**proposal** (`mode: "proposal"`, held for human review) instead of publishing
-immediately when ALL of:
+**proposal** (`mode: "proposal"`, held for human review) when any cited source
+has `answerPolicy.reviewRequired: true`. Otherwise the workspace approval
+behavior applies when ALL of:
 
 - `proposalMode !== "never"`, and
 - `tier === "company"`, and
@@ -163,7 +174,7 @@ AGENTS.md carries a one-line action index; these are the fuller purposes.
 | `ask-brain` | Cited-answer endpoint: reviewed knowledge, capped raw-capture fallback, citations, `federatedCoverage`. |
 | `get-knowledge` / `list-knowledge` | Read one or list distilled knowledge records. |
 | `get-capture` / `list-captures` | Read one or list raw captures (redacted by default; `includeRawContent` for exact quotes). |
-| `import-capture` / `import-transcript` | Ingest a generic capture or a meeting transcript; auto-creates a `manual` source. |
+| `import-capture` / `import-transcript` | Ingest a generic capture or meeting transcript, auto-create a `manual` source when needed, and queue distillation by default. |
 | `enqueue-distillation` / `mark-capture-distilled` | Queue a capture for distillation; close out the queue row when done. |
 | `write-knowledge` | Write/update durable knowledge; may return a pending proposal — see Publish Tiers above. |
 | `review-proposal` / `approve-proposal` / `reject-proposal` / `list-proposals` / `update-proposal` | Human-review workflow for gated writes. |

package/corpus/templates/brain/.agents/skills/ingestion-and-connectors/SKILL.md

@@ -35,6 +35,37 @@ retrieved again later. Surface it to the user immediately (e.g. for wiring
 into an external system's webhook config) rather than assuming you can read
 it back with `get-source`.
 
+## Blessed FAQ And Docs Publishers
+
+Approved FAQs, docs, handbooks, and similar owned resources use the same
+`generic` signed source contract. They are not a new provider and do not require
+Brain to crawl the entire upstream system. The source owner publishes only the
+records Brain is allowed to use:
+
+```bash
+pnpm --filter brain action create-source \
+  --title "Blessed Agent Native docs" \
+  --provider generic \
+  --sourceKey agent-native-docs \
+  --policy '{"trustTier":"blessed","answerEligible":true,"authority":100,"freshnessWindowDays":null,"reviewRequired":false,"conflictBehavior":"prefer-higher-authority"}' \
+  --visibility org
+```
+
+The source answer policy is code-enforced:
+
+| Field                 | Effect                                                                              |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `trustTier`           | `blessed`, `standard`, or `untrusted`; cited answers rank higher trust first.       |
+| `answerEligible`      | Excludes the source from `ask-brain` answers when false.                            |
+| `authority`           | Ranks otherwise eligible sources from 0 to 100.                                     |
+| `freshnessWindowDays` | Excludes source-backed results after the configured window; `null` disables expiry. |
+| `reviewRequired`      | Raw captures cannot support answers, and company knowledge enters review.           |
+| `conflictBehavior`    | Prefer higher authority, surface conflicts, or require review before raw support.   |
+
+Legacy sources remain `standard`, answer-eligible, authority 50, with no
+freshness expiry. Use `update-source --policy ...` to tighten an existing
+source without recreating it.
+
 ## Source Health States
 
 `get-brain-health` (`readBrainHealth` in `server/lib/brain-health.ts`) is the
@@ -105,7 +136,8 @@ connection, not creating a new one.
 
 ## Editing And Removing Sources
 
-- `update-source` edits title, config, or visibility on an existing source.
+- `update-source` edits title, config, cursor, status, or answer policy on an
+  existing source.
 - `delete-source` is a hard delete — there's no soft-archive alternative
   exposed as an action; setting `status: "paused"` via `update-source` is the
   reversible way to stop a source without losing its captures.

package/corpus/templates/brain/AGENTS.md

@@ -58,6 +58,8 @@ Read the matching skill before deeper work:
   from `get-capture` output.
 - Sources support exactly six providers: `manual`, `generic`, `clips`, `slack`,
   `granola`, `github`. `create-source` rejects anything else.
+- Use a blessed `generic` source for approved FAQs, docs, and handbooks. See
+  `ingestion-and-connectors` for answer policy, updates, and deletion semantics.
 - Reuse existing workspace integration grants (check `list-connection-providers`
   readiness) instead of duplicating provider tokens into Brain. Source sync
   actions are convenience readers, not integration limits — for an endpoint,
@@ -87,7 +89,7 @@ Read the matching skill before deeper work:
 | `ask-brain` | Cited-answer endpoint with `federatedCoverage`. |
 | `get-knowledge` / `list-knowledge` | Read or list distilled knowledge. |
 | `get-capture` / `list-captures` | Read or list raw captures (redacted by default). |
-| `import-capture` / `import-transcript` | Ingest a capture or meeting transcript. |
+| `import-capture` / `import-transcript` | Ingest and queue a capture or transcript for distillation. |
 | `enqueue-distillation` / `mark-capture-distilled` | Queue distillation; close the queue row. |
 | `write-knowledge` | Write/update knowledge; may return a pending proposal. |
 | `review-proposal` / `approve-proposal` / `reject-proposal` / `list-proposals` / `update-proposal` | Human review of gated writes. |

package/corpus/templates/brain/README.md

@@ -15,7 +15,8 @@ attendee-scoped meetings without widening their audience.
 ## Features
 
 - Company chat that answers from cited, reviewed knowledge — not hallucinations.
-- Source connectors for Slack, Granola, GitHub, Clips, and generic webhooks.
+- Source connectors for Slack, Granola, GitHub, Clips, and generic webhooks,
+  including source-owner-published blessed FAQs and docs.
 - Deterministic privacy screening before storage, with an optional approved
   privacy classifier for richer review decisions.
 - Hybrid full-text and semantic search over allowed captures and knowledge,
@@ -25,6 +26,8 @@ attendee-scoped meetings without widening their audience.
 - Sensitive sources are suppressed or quarantined before search, citations,
   distillation, and source editors can see their content.
 - Read-only, citation-backed retrieval exposed to other apps over A2A.
+- Per-source answer policy for trust, eligibility, authority, freshness,
+  review, and conflict handling.
 
 ## Privacy posture
 

package/corpus/templates/brain/actions/_schemas.ts

@@ -1,5 +1,13 @@
 import { z } from "zod";
 
+export const booleanishSchema = z.preprocess((value) => {
+  if (typeof value !== "string") return value;
+  const normalized = value.trim().toLowerCase();
+  if (["true", "1", "yes", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "off"].includes(normalized)) return false;
+  return value;
+}, z.boolean());
+
 export const sourceProviderSchema = z.enum([
   "manual",
   "generic",
@@ -9,6 +17,28 @@ export const sourceProviderSchema = z.enum([
   "github",
 ]);
 
+export const sourceAnswerPolicySchema = z.preprocess(
+  parseJsonCliInput,
+  z
+    .object({
+      trustTier: z.enum(["blessed", "standard", "untrusted"]).optional(),
+      answerEligible: booleanishSchema.optional(),
+      authority: z.coerce.number().int().min(0).max(100).optional(),
+      freshnessWindowDays: z
+        .union([z.null(), z.coerce.number().int().min(0).max(3650)])
+        .optional(),
+      reviewRequired: booleanishSchema.optional(),
+      conflictBehavior: z
+        .enum([
+          "prefer-higher-authority",
+          "surface-conflicts",
+          "require-review",
+        ])
+        .optional(),
+    })
+    .strict(),
+);
+
 export const captureKindSchema = z.enum([
   "transcript",
   "note",
@@ -76,14 +106,6 @@ export const optionalJsonRecordSchema = z
   .preprocess(parseJsonCliInput, z.record(z.string(), z.unknown()).optional())
   .optional();
 
-export const booleanishSchema = z.preprocess((value) => {
-  if (typeof value !== "string") return value;
-  const normalized = value.trim().toLowerCase();
-  if (["true", "1", "yes", "on"].includes(normalized)) return true;
-  if (["false", "0", "no", "off"].includes(normalized)) return false;
-  return value;
-}, z.boolean());
-
 export function stringArrayCliSchema({
   min,
   max,

package/corpus/templates/brain/actions/ask-brain.ts

@@ -13,6 +13,13 @@ import {
   searchEverythingRows,
   type UniversalSearchResult,
 } from "../server/lib/search.js";
+import {
+  compareEvaluatedSourcePolicies,
+  evaluateSourceAnswerPolicy,
+  loadAccessibleSourcePolicySnapshots,
+  type EvaluatedSourceAnswerPolicy,
+  type SourcePolicySnapshot,
+} from "../server/lib/source-policy.js";
 
 const STOPWORDS = new Set([
   "about",
@@ -96,7 +103,7 @@ function rankRowsForQuestion(rows: KnowledgeSearchRow[], question: string) {
   const minimumScore = bestScore >= 3 ? Math.max(2, bestScore - 2) : 0;
   return ranked
     .filter((entry) => entry.score >= minimumScore)
-    .slice(0, 6)
+    .slice(0, 24)
     .map((entry) => entry.row);
 }
 
@@ -116,6 +123,54 @@ function captureDeepLink(captureId: string): string {
   });
 }
 
+function knowledgeSourceIds(
+  item: ReturnType<typeof serializeKnowledge>,
+): string[] {
+  return Array.from(
+    new Set(
+      [
+        item.sourceId,
+        ...item.evidence.map((evidence) => evidence.sourceId),
+      ].filter((id): id is string => Boolean(id)),
+    ),
+  );
+}
+
+function sourcePolicyEnforcement(args: {
+  policies: Map<string, SourcePolicySnapshot>;
+  knowledgeEvaluated: number;
+  captureEvaluated: number;
+  excludedKnowledge: number;
+  excludedCaptures: number;
+}) {
+  return {
+    enforced: true,
+    legacyDefault: {
+      trustTier: "standard" as const,
+      answerEligible: true,
+      authority: 50,
+    },
+    ranking: ["trustTier", "authority", "relevance"],
+    configuredSources: Array.from(args.policies.values()).map((policy) => ({
+      sourceId: policy.sourceId,
+      trustTier: policy.trustTier,
+      answerEligible: policy.answerEligible,
+      authority: policy.authority,
+      freshnessWindowDays: policy.freshnessWindowDays,
+      reviewRequired: policy.reviewRequired,
+      conflictBehavior: policy.conflictBehavior,
+    })),
+    evaluated: {
+      knowledge: args.knowledgeEvaluated,
+      captures: args.captureEvaluated,
+    },
+    excluded: {
+      knowledge: args.excludedKnowledge,
+      captures: args.excludedCaptures,
+    },
+  };
+}
+
 export default defineAction({
   description:
     "Answer a company-knowledge question from published Brain knowledge, falling back to cited raw capture matches when approved knowledge is thin. The external-facing public-agent company lookup: returns a cited answer plus deep links into the Brain knowledge/capture records.",
@@ -137,17 +192,36 @@ export default defineAction({
     const seen = new Set<string>();
     const rows = [];
     for (const facet of facetsFromQuestion(question)) {
-      const matches = await searchKnowledgeRows({ query: facet, limit: 6 });
+      const matches = await searchKnowledgeRows({ query: facet, limit: 24 });
       for (const row of matches) {
         if (seen.has(row.id)) continue;
         seen.add(row.id);
         rows.push(row);
       }
-      if (rows.length >= 6) break;
+      if (rows.length >= 24) break;
     }
-    const knowledge = rankRowsForQuestion(rows, question).map(
+    const knowledgeCandidates = rankRowsForQuestion(rows, question).map(
       serializeKnowledge,
     );
+    const sourcePolicies = await loadAccessibleSourcePolicySnapshots(
+      knowledgeCandidates.flatMap(knowledgeSourceIds),
+    );
+    const evaluatedKnowledge = knowledgeCandidates.map((item) => ({
+      ...item,
+      answerPolicy: evaluateSourceAnswerPolicy({
+        sourceIds: knowledgeSourceIds(item),
+        sourcePolicies,
+        contentUpdatedAt: item.updatedAt,
+        resultType: "knowledge",
+        reviewed: item.status === "published",
+      }),
+    }));
+    const knowledge = evaluatedKnowledge
+      .filter((item) => item.answerPolicy.eligible)
+      .sort((left, right) =>
+        compareEvaluatedSourcePolicies(left.answerPolicy, right.answerPolicy),
+      )
+      .slice(0, 6);
     const captureFallback: UniversalSearchResult[] = [];
     const knowledgeTextLength = knowledge.reduce(
       (total, item) => total + `${item.summary} ${item.body}`.trim().length,
@@ -163,18 +237,49 @@ export default defineAction({
         const matches = await searchEverythingRows({
           query: facet,
           type: "capture",
-          limit: 6,
+          limit: 24,
         });
         for (const match of matches) {
           if (seenCaptures.has(match.id)) continue;
           seenCaptures.add(match.id);
           captureFallback.push(match);
         }
-        if (captureFallback.length >= 4) break;
+        if (captureFallback.length >= 24) break;
       }
     }
+    const captureSourcePolicies = await loadAccessibleSourcePolicySnapshots(
+      captureFallback.flatMap((item) =>
+        item.source?.id ? [item.source.id] : [],
+      ),
+    );
+    for (const [sourceId, policy] of captureSourcePolicies) {
+      sourcePolicies.set(sourceId, policy);
+    }
+    const evaluatedCaptures = captureFallback.map((item) => ({
+      ...item,
+      answerPolicy: evaluateSourceAnswerPolicy({
+        sourceIds: item.source?.id ? [item.source.id] : [],
+        sourcePolicies,
+        contentUpdatedAt: item.updatedAt,
+        resultType: "capture",
+        reviewed: false,
+      }),
+    }));
+    const eligibleCaptures = evaluatedCaptures
+      .filter((item) => item.answerPolicy.eligible)
+      .sort((left, right) =>
+        compareEvaluatedSourcePolicies(left.answerPolicy, right.answerPolicy),
+      )
+      .slice(0, 4);
+    const sourcePolicy = sourcePolicyEnforcement({
+      policies: sourcePolicies,
+      knowledgeEvaluated: evaluatedKnowledge.length,
+      captureEvaluated: evaluatedCaptures.length,
+      excludedKnowledge: evaluatedKnowledge.length - knowledge.length,
+      excludedCaptures: evaluatedCaptures.length - eligibleCaptures.length,
+    });
 
-    if (!knowledge.length && !captureFallback.length) {
+    if (!knowledge.length && !eligibleCaptures.length) {
       const federatedCoverage = await federatedCoveragePromise;
       return {
         answer:
@@ -186,6 +291,7 @@ export default defineAction({
         captures: [],
         results: [],
         policy: guidance.retrieval,
+        sourcePolicy,
         responseGuidance: guidance.response,
         federatedCoverage,
       };
@@ -201,9 +307,10 @@ export default defineAction({
         confidence: item.confidence / 100,
         url: safeCitationUrl(evidence.sourceUrl ?? evidence.url),
         deepLink: knowledgeDeepLink(item.id),
+        sourcePolicy: item.answerPolicy,
       })),
     );
-    const captureCitations = captureFallback.map((item) => ({
+    const captureCitations = eligibleCaptures.map((item) => ({
       id: item.id,
       captureId: item.id,
       title: item.title,
@@ -211,6 +318,7 @@ export default defineAction({
       excerpt: item.snippet,
       url: safeCitationUrl(item.sourceUrl),
       deepLink: captureDeepLink(item.id),
+      sourcePolicy: item.answerPolicy,
     }));
     const answerParts = [];
     const hasCitations = knowledgeCitations.length || captureCitations.length;
@@ -221,9 +329,10 @@ export default defineAction({
           "I found possible Brain context, but workspace settings require citations and these results did not include usable evidence.",
         citations: [],
         knowledge,
-        captures: captureFallback,
-        results: captureFallback,
+        captures: eligibleCaptures,
+        results: eligibleCaptures,
         policy: guidance.retrieval,
+        sourcePolicy,
         responseGuidance: guidance.response,
         federatedCoverage,
       };
@@ -235,14 +344,14 @@ export default defineAction({
           .join("\n\n"),
       );
     }
-    if (captureFallback.length) {
+    if (eligibleCaptures.length) {
       const prefix = knowledge.length
         ? "Related raw capture matches:"
         : "I could not find approved Brain knowledge, but I found matching raw captures:";
       answerParts.push(
         [
           prefix,
-          ...captureFallback.map(
+          ...eligibleCaptures.map(
             (item) =>
               `${item.title}${item.source?.title ? ` (${item.source.title})` : ""}: ${item.snippet}`,
           ),
@@ -258,9 +367,10 @@ export default defineAction({
       citations,
       deepLink: primary?.deepLink ?? null,
       knowledge,
-      captures: captureFallback,
-      results: captureFallback,
+      captures: eligibleCaptures,
+      results: eligibleCaptures,
       policy: guidance.retrieval,
+      sourcePolicy,
       responseGuidance: guidance.response,
       federatedCoverage,
     };

package/corpus/templates/brain/actions/create-source.ts

@@ -8,7 +8,12 @@ import {
   sha256Hex,
 } from "../server/lib/brain.js";
 import { assertSourceWorkspaceConnectionAvailable } from "../server/lib/source-credentials.js";
-import { jsonRecordSchema, sourceProviderSchema } from "./_schemas.js";
+import { withSourceAnswerPolicy } from "../server/lib/source-policy.js";
+import {
+  jsonRecordSchema,
+  sourceAnswerPolicySchema,
+  sourceProviderSchema,
+} from "./_schemas.js";
 
 export default defineAction({
   description:
@@ -27,9 +32,20 @@ export default defineAction({
       .optional()
       .describe("Optional signed-ingest bearer token; stored only as a hash"),
     visibility: z.enum(["private", "org"]).default("org"),
+    policy: sourceAnswerPolicySchema
+      .optional()
+      .describe(
+        "Optional answer policy controlling trust, eligibility, authority, freshness, review, and conflicts",
+      ),
   }),
   run: async (args) => {
-    const config = { ...args.config };
+    let config = { ...args.config };
+    if (args.policy !== undefined || config.answerPolicy !== undefined) {
+      config = withSourceAnswerPolicy(
+        config,
+        args.policy ?? config.answerPolicy,
+      );
+    }
     const workspaceConnectionId =
       typeof config.workspaceConnectionId === "string"
         ? config.workspaceConnectionId.trim()