@agentskit/doc-bridge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/docs/DOGFOOD-ROUND2.md

@@ -0,0 +1,142 @@
+# Dogfood round 2 — published `@agentskit/doc-bridge@0.1.0-alpha.2`
+
+**Date:** 2026-07-09  
+**Install:** npm registry tag `alpha` → `0.1.0-alpha.2`  
+**Consumers:** agentskit · agentskit-os · agents-playbook · agentskit-registry  
+
+## Scoreboard
+
+| Repo | Install | Version | Knowledge | Handoffs | Gate | Sample handoff quality |
+|------|---------|---------|-----------|----------|------|------------------------|
+| **agentskit** | `pnpm add -Dw @0.1.0-alpha.2` ✅ | 0.1.0-alpha.2 | 25 | 24 | ✅ freshness + 23 humanDoc | Excellent: pnpm filter checks + humanDoc `/docs/reference/packages/core` |
+| **agentskit-os** | pnpm store conflict; used **`npx`** ✅ | 0.1.0-alpha.2 | 170 | 92 | ✅ freshness + 9 humanDoc | Good act path; weak human bridge (9/92) |
+| **agents-playbook** | `pnpm add -D` ✅ | 0.1.0-alpha.2 | 127 | 81 | ✅ freshness + okf-type | Pattern ownership + `check:okf-type` ✅ |
+| **agentskit-registry** | needs `--legacy-peer-deps` ⚠️ | 0.1.0-alpha.2 | 36 | 36 | ✅ freshness | Full agent ownership + humanDoc ✅ |
+
+### npm dist-tags (observed)
+
+| Tag | Version |
+|-----|---------|
+| `latest` | `0.1.0-alpha.1` |
+| `alpha` | `0.1.0-alpha.2` |
+
+**Recommendation:** keep prereleases only on `alpha` until stable; document `npm i -D @agentskit/doc-bridge@alpha`.
+
+---
+
+## What works well (validated)
+
+1. **Published binary works** — `ak-docs 0.1.0-alpha.2` from registry / npx.
+2. **Monorepo handoffs** — `editRoots` + `pnpm --filter @agentskit/<pkg> test|lint` on agentskit and AKOS.
+3. **Playbook preset** — gates green without crushing large OKF corpus.
+4. **Registry ownership** — all 36 agents resolve; checks use `npm run validate`.
+5. **Fumadocs humanDoc** on agentskit points at **reference** docs, not nested for-agents.
+6. **Pattern checks** — playbook patterns emit `pnpm run check:okf-type`.
+
+---
+
+## Issues found (prioritized)
+
+### P0 — correctness / ranking (agents will take wrong action)
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-1** | **Search/ask ranking ignores exact package id** | `search core --agent` bestMatch = **angular** (score 8) tied with **core** (score 8) because summary contains `@agentskit/core` | Boost exact `id` / path segment matches; prefer ownership id === term before body mentions |
+| **R2-2** | **`ask` suggests wrong handoff** | “where do I change the **core** package?” → best match **angular**, next `query ownership angular` | Same ranking fix; optional: prefer ownership over knowledge for “package/module” language |
+| **R2-3** | **Purpose/notes truncated mid-sentence** | core notes: `"Stable TypeScript contracts (Adapter, Tool, Memory, Retriever, Skill,"` | Raise firstParagraph budget; strip trailing incomplete commas; prefer frontmatter `purpose` full line |
+
+### P1 — install / peer DX
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-4** | **Optional peers still break npm install** | registry: `ERESOLVE` with optional peers vs `@agentskit/adapters@0.12.x` | Peer ranges more permissive (`>=0.12` / `>=1.0`); document `--legacy-peer-deps`; ensure optional peers never hard-fail Layer 0 |
+| **R2-5** | **Peer `@agentskit/core@^1.10.0` vs monorepo 1.9.0** | pnpm warning on agentskit install | Align peer to `^1.9.0 \|\| ^1.10.0` or `>=1.9.0 <2` for dogfood until monorepo bumps |
+| **R2-6** | **`latest` still points at alpha.1** | `npm view` latest=alpha.1, alpha=alpha.2 | Publish hygiene: don’t put prereleases on `latest`, or retag after publish |
+| **R2-7** | **AKOS cannot `pnpm add` (store v10 vs v11)** | `ERR_PNPM_UNEXPECTED_STORE` | Docs: use npx / align store; not a doc-bridge bug but dogfood friction |
+
+### P2 — search / retrieval quality
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-8** | **Search miss on common English** | agentskit `search documentation` → **0 matches** | Index more body text / titles; lower threshold; BM25 over full file not only description |
+| **R2-9** | **Playbook `search handoff` → 0** | term may only appear deep in body | Same as R2-8; chunk full markdown into search corpus |
+| **R2-10** | **Federation hard-fail noise** | `retrieve` → `Failed to fetch https://registry.agentskit.io/llms.txt: 404` | Soft-fail federation sources; warn once; don’t fail command |
+| **R2-11** | **Text search UX** | tab-separated dense lines | Columnar/TTY formatting (`type  id  path  summary`) |
+
+### P3 — bridge coverage & product polish
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-12** | **AKOS humanDoc still sparse** | 9/92 handoffs with humanDoc | Map for-agents frontmatter `humanDoc`; product Fumadocs catalog; optional plain-markdown `docs/errors` etc. |
+| **R2-13** | **Duplicate knowledge+ownership rows in search** | same path appears as ownership + knowledge | Deduplicate by path; show ownership preferred |
+| **R2-14** | **Default checks for patterns without okf script** | N/A playbook ok | Fine; document convention |
+| **R2-15** | **MCP not re-smoked this round** | — | Keep in CI smoke; optional round 3 |
+
+---
+
+## Sample outputs (good)
+
+### agentskit — `query package core --agent`
+
+```json
+{
+  "startHere": "apps/docs-next/content/docs/for-agents/core.mdx",
+  "editRoots": ["packages/core"],
+  "checks": [
+    "pnpm --filter @agentskit/core test",
+    "pnpm --filter @agentskit/core lint"
+  ],
+  "humanDoc": "/docs/reference/packages/core"
+}
+```
+
+### playbook — pattern handoff
+
+```json
+{
+  "startHere": "content/docs/pillars/ai-collaboration/open-knowledge-format-pattern.md",
+  "checks": ["pnpm run check:okf-type"],
+  "humanDoc": "/docs/pillars/ai-collaboration/open-knowledge-format-pattern"
+}
+```
+
+### registry — `docs-chat`
+
+```json
+{
+  "startHere": "registry/docs-chat/README.md",
+  "editRoots": ["registry/docs-chat"],
+  "checks": ["npm run validate", "npm test"],
+  "humanDoc": "/agents/docs-chat"
+}
+```
+
+---
+
+## Recommended next alpha (0.1.0-alpha.3) scope
+
+1. **Ranking:** exact id / basename boost; package-intent heuristics for `ask`
+2. **Search corpus:** full-text over body (not only description); dedupe paths
+3. **Descriptions:** full purpose from frontmatter or first complete paragraph
+4. **Peers:** widen optional peer ranges; Layer 0 install never requires AgentsKit packages
+5. **Federation:** soft-fail missing `llms.txt` sources
+6. **Publish:** keep `latest` free of broken prereleases; doc install as `@alpha`
+
+---
+
+## Consumer follow-ups (not doc-bridge code)
+
+| Repo | Action |
+|------|--------|
+| agentskit | Bump `@agentskit/core` to 1.10+ or live with peer warning |
+| agentskit-os | Align pnpm store / commit lock with published dep; add CI `docs:bridge:gate` |
+| agents-playbook | Optional CI workflow for gate |
+| agentskit-registry | Publish `public/llms.txt` at site root (404 today); use `--legacy-peer-deps` until peer ranges loosen |
+| all | After alpha.3: switch dep to `@agentskit/doc-bridge@alpha` only |
+
+---
+
+## Conclusion
+
+**Round 2 proves Layer 0 is useful on real monorepos and OKF/registry corpora with the published package.**  
+The biggest remaining gap for “agents do the right thing” is **discovery ranking (R2-1/R2-2)** and **search body coverage (R2-8/R2-9)** — not indexing or handoff structure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
   "bin": {
@@ -46,9 +46,9 @@
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && pnpm test && changeset publish",
-    "prepublishOnly": "npm run build && npm test",
+    "prepublishOnly": "pnpm build && pnpm test",
     "prepare": "node scripts/prepare.mjs",
-    "prepack": "npm run build"
+    "prepack": "pnpm build"
   },
   "keywords": [
     "agentskit",
@@ -75,11 +75,11 @@
     "zod": "^3.24.2"
   },
   "peerDependencies": {
-    "@agentskit/adapters": "^0.13.0",
-    "@agentskit/core": "^1.10.0",
-    "@agentskit/ink": "^0.9.0",
-    "@agentskit/memory": "^0.10.0",
-    "@agentskit/rag": "^0.4.0",
+    "@agentskit/adapters": ">=0.12.0 <1",
+    "@agentskit/core": ">=1.0.0 <2",
+    "@agentskit/ink": ">=0.8.0 <1",
+    "@agentskit/memory": ">=0.9.0 <1",
+    "@agentskit/rag": ">=0.3.0 <1",
     "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {

package/src/cli/program.ts

@@ -160,9 +160,11 @@ const writeTextQuery = (payload: unknown): void => {
     writeLines([
       `Search: ${String(data.term ?? '')}`,
       `Matches: ${String(data.count ?? matches.length)}`,
-      ...matches.map((match) =>
-        [match.type, match.id, match.path, match.summary].filter(Boolean).join('\t'),
-      ),
+      ...(matches.length
+        ? matches.map((match) =>
+            formatSearchMatch(match as { type: string; id: string; path: string; summary?: string }),
+          )
+        : ['  (none)']),
     ])
     return
   }
@@ -170,6 +172,18 @@ const writeTextQuery = (payload: unknown): void => {
   writeLines([textValue(result.data)])
 }
 
+const formatSearchMatch = (match: {
+  readonly type: string
+  readonly id: string
+  readonly path: string
+  readonly summary?: string
+  readonly score?: number
+}): string => {
+  const summary = match.summary ? match.summary.replace(/\s+/g, ' ').slice(0, 100) : ''
+  const score = typeof match.score === 'number' ? ` score=${match.score}` : ''
+  return `  [${match.type}] ${match.id}${score}\n    ${match.path}${summary ? `\n    ${summary}` : ''}`
+}
+
 const writeTextSearch = (
   term: string,
   matches: readonly {
@@ -177,14 +191,13 @@ const writeTextSearch = (
     readonly id: string
     readonly path: string
     readonly summary?: string
+    readonly score?: number
   }[],
 ): void => {
   writeLines([
     `Search: ${term}`,
     `Matches: ${matches.length}`,
-    ...matches.map((match) =>
-      [match.type, match.id, match.path, match.summary].filter(Boolean).join('\t'),
-    ),
+    ...(matches.length ? matches.map(formatSearchMatch) : ['  (none)']),
   ])
 }
 
@@ -193,11 +206,14 @@ const writeAsk = (
   matches: ReturnType<typeof searchIndex>,
   index: DocBridgeIndexV1,
 ): void => {
-  const best = matches[0]
-  const owner = matches.find((match) => match.type === 'ownership' || index.lookup?.ownership?.[match.id])
+  // Prefer ownership match for routing questions
+  const owner =
+    matches.find((match) => match.type === 'ownership') ??
+    matches.find((match) => Boolean(index.lookup?.ownership?.[match.id]))
+  const best = owner ?? matches[0]
   const bestQuery =
-    owner
-      ? `ak-docs query ownership ${owner.id} --agent`
+    best && (best.type === 'ownership' || index.lookup?.ownership?.[best.id])
+      ? `ak-docs query ownership ${best.id} --agent`
       : 'ak-docs list knowledge --text'
   writeLines([
     `Question: ${question}`,
@@ -206,10 +222,8 @@ const writeAsk = (
     'Matches:',
     ...(
       matches.length
-        ? matches.slice(0, 5).map((match) =>
-            [match.type, match.id, match.path, match.summary].filter(Boolean).join('\t'),
-          )
-        : ['No local matches. Try: ak-docs search <term>']
+        ? matches.slice(0, 5).map(formatSearchMatch)
+        : ['  No local matches. Try: ak-docs search <term>']
     ),
     '',
     'Next commands:',

package/src/federation/llms.ts

@@ -35,11 +35,15 @@ const sourceText = async (
   root: string,
   source: string,
   fetchText: FetchText,
-): Promise<string> => {
-  if (/^https?:\/\//.test(source)) return fetchText(source)
-  const path = resolve(root, source)
-  if (!existsSync(path)) throw new Error(`Federation source not found: ${source}`)
-  return readFileSync(path, 'utf8')
+): Promise<string | null> => {
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source)
+    const path = resolve(root, source)
+    if (!existsSync(path)) return null
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
 }
 
 const sameOrigin = (base: string, target: string): boolean => {
@@ -97,9 +101,14 @@ export const loadFederatedChunks = async (
 ): Promise<DocBridgeRetrievedChunk[]> => {
   const fetchText = options.fetchText ?? defaultFetchText
   const chunks: DocBridgeRetrievedChunk[] = []
+  const warnings: string[] = []
   for (const source of config.federation?.sources ?? []) {
     if (source.includeInRetriever === false || !source.llmsTxt) continue
     const llms = await sourceText(root, source.llmsTxt, fetchText)
+    if (!llms) {
+      warnings.push(`federation source skipped (unavailable): ${source.id} → ${source.llmsTxt}`)
+      continue
+    }
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt))
     const links = parseLlmsTxtLinks(llms)
     for (const link of links) {
@@ -108,14 +117,14 @@ export const loadFederatedChunks = async (
         : link.url
       if (!/\.(md|txt)(?:$|\?)/.test(url)) continue
       if (!sameOrigin(source.llmsTxt, url)) continue
-      try {
-        const raw = await sourceText(root, url, fetchText)
-        chunks.push(...chunksFromMarkdown(source.id, raw, url))
-      } catch {
-        // ponytail: federation is best-effort; surface-level health belongs in a future diagnostic command.
-      }
+      const raw = await sourceText(root, url, fetchText)
+      if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url))
     }
   }
+  // Soft-fail: never throw for missing remote sources; one-line warn for agents/humans.
+  if (warnings.length && process.stderr.isTTY) {
+    for (const w of warnings) process.stderr.write(`${w}\n`)
+  }
   return chunks
 }
 

package/src/index-builder/build-handoffs.ts

@@ -103,16 +103,31 @@ const resolveHumanDoc = (
   if (override) return override
   if (fmHuman) return fmHuman
   if (humanDocs[packageId]) return humanDocs[packageId]
-  // common aliases: scoped package name tail, path segments
+
   const aliases = [
     packageId,
     packageId.replace(/^@[^/]+\//, ''),
     packageId.replace(/^os-/, ''),
     packageId.replace(/-pattern$/, ''),
+    `packages/${packageId}`,
+    `reference/packages/${packageId}`,
+    `packages/${packageId}/index`,
   ]
   for (const alias of aliases) {
     if (humanDocs[alias]) return humanDocs[alias]
   }
+
+  // Fuzzy: id is a path segment or suffix of a human doc id
+  for (const [key, url] of Object.entries(humanDocs)) {
+    if (
+      key === packageId ||
+      key.endsWith(`/${packageId}`) ||
+      key.endsWith(`/${packageId}/index`) ||
+      key.endsWith(`-${packageId}`)
+    ) {
+      return url
+    }
+  }
   return undefined
 }
 

package/src/index-builder/scan-corpus.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import {
+  extractSearchBody,
   firstHeading,
   firstParagraph,
   frontmatterString,
@@ -47,7 +48,9 @@ export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): Corpus
       frontmatterString(frontmatter, 'package') ??
       slugFromPath(relToCorpus)
     const title = firstHeading(raw) ?? id
-    const description = firstParagraph(raw)
+    const purpose = frontmatterString(frontmatter, 'purpose')
+    const description = purpose ?? firstParagraph(raw, 400)
+    const body = extractSearchBody(raw)
     return {
       id,
       type: 'agent-doc',
@@ -57,6 +60,7 @@ export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): Corpus
       relPath,
       frontmatter,
       ...(description ? { description } : {}),
+      ...(body ? { body } : {}),
     }
   })
 }

package/src/lib/markdown.ts

@@ -64,7 +64,8 @@ export const firstHeading = (markdown: string): string | undefined => {
   return undefined
 }
 
-export const firstParagraph = (markdown: string): string | undefined => {
+/** Complete first prose block — prefer full sentences, cap length without mid-word cuts. */
+export const firstParagraph = (markdown: string, maxLen = 400): string | undefined => {
   const { body } = parseFrontmatter(markdown)
   const lines = body.split('\n')
   const buf: string[] = []
@@ -76,11 +77,37 @@ export const firstParagraph = (markdown: string): string | undefined => {
     }
     if (t.startsWith('#')) continue
     if (t.startsWith('---')) continue
+    if (t.startsWith('```')) break
+    if (t.startsWith('|') || t.startsWith('- [') || t.startsWith('* [')) {
+      if (buf.length) break
+      continue
+    }
     buf.push(t)
-    if (buf.join(' ').length > 40) break
+    if (buf.join(' ').length >= maxLen) break
   }
-  const text = buf.join(' ').trim()
-  return text || undefined
+  let text = buf.join(' ').replace(/\s+/g, ' ').trim()
+  if (!text) return undefined
+  if (text.length <= maxLen) return text
+  // Prefer ending on sentence boundary
+  const sliced = text.slice(0, maxLen)
+  const sentenceEnd = Math.max(sliced.lastIndexOf('. '), sliced.lastIndexOf('! '), sliced.lastIndexOf('? '))
+  if (sentenceEnd > maxLen * 0.4) return sliced.slice(0, sentenceEnd + 1).trim()
+  const wordEnd = sliced.lastIndexOf(' ')
+  return (wordEnd > 0 ? sliced.slice(0, wordEnd) : sliced).trim()
+}
+
+/** Flatten markdown body for search (strip fences/links noise lightly). */
+export const extractSearchBody = (markdown: string, maxLen = 6_000): string => {
+  const { body } = parseFrontmatter(markdown)
+  const text = body
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, ' ')
+    .replace(/\[[^\]]*\]\([^)]+\)/g, ' ')
+    .replace(/^#+\s+/gm, '')
+    .replace(/[|>*_`#]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.length > maxLen ? text.slice(0, maxLen) : text
 }
 
 export const slugFromPath = (relPath: string): string => {

package/src/query/search.ts

@@ -11,23 +11,80 @@ export type SearchMatch = {
 const tokenize = (value: string): string[] =>
   value
     .toLowerCase()
-    .split(/[^a-z0-9]+/)
+    .split(/[^a-z0-9@/_-]+/)
     .filter((t) => t.length >= 2)
 
+const PACKAGE_INTENT =
+  /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b/i
+
+const scoreHay = (tokens: readonly string[], hay: string, weight = 1): number => {
+  let score = 0
+  for (const token of tokens) {
+    if (!hay.includes(token)) continue
+    score += token.length * weight
+    // whole-word-ish bonus
+    if (new RegExp(`(?:^|[^a-z0-9])${token}(?:[^a-z0-9]|$)`).test(hay)) {
+      score += token.length
+    }
+  }
+  return score
+}
+
+/** Exact / near-exact identity boost so "core" ranks the core package over mentions of @agentskit/core. */
+const identityBoost = (id: string, path: string, tokens: readonly string[], term: string): number => {
+  const idLower = id.toLowerCase()
+  const termLower = term.toLowerCase().trim()
+  const base = path.split('/').pop()?.replace(/\.mdx?$/i, '').toLowerCase() ?? ''
+  let boost = 0
+
+  if (idLower === termLower || base === termLower) boost += 200
+  if (tokens.length === 1 && (idLower === tokens[0] || base === tokens[0])) boost += 200
+
+  for (const token of tokens) {
+    if (idLower === token) boost += 120
+    else if (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`)) boost += 40
+    else if (idLower.includes(token) && idLower.length <= token.length + 4) boost += 30
+    if (base === token) boost += 100
+  }
+
+  // Prefer short ids when term is the id (package name)
+  if (tokens.includes(idLower)) boost += Math.max(0, 40 - idLower.length)
+
+  return boost
+}
+
+const preferOwnership = (term: string): boolean =>
+  PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term)
+
 export const searchIndex = (index: DocBridgeIndexV1, term: string, limit = 20): SearchMatch[] => {
   const tokens = tokenize(term)
   if (!tokens.length) return []
 
-  const matches: SearchMatch[] = []
+  const wantOwnership = preferOwnership(term)
+  const byPath = new Map<string, SearchMatch>()
 
-  for (const entry of index.knowledge) {
-    const hay = `${entry.id} ${entry.title} ${entry.description ?? ''} ${entry.path}`.toLowerCase()
-    let score = 0
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length
+  const consider = (match: SearchMatch) => {
+    const key = match.path
+    const existing = byPath.get(key)
+    if (!existing) {
+      byPath.set(key, match)
+      return
     }
+    // Prefer ownership over knowledge for same path; else higher score
+    const prefer =
+      match.score > existing.score ||
+      (match.score === existing.score && match.type === 'ownership' && existing.type !== 'ownership') ||
+      (wantOwnership && match.type === 'ownership' && existing.type !== 'ownership' && match.score >= existing.score - 20)
+    if (prefer) byPath.set(key, match)
+  }
+
+  for (const entry of index.knowledge) {
+    const body = (entry as { body?: string }).body ?? ''
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ''} ${entry.path} ${body}`.toLowerCase()
+    let score = scoreHay(tokens, hay, 1)
+    score += identityBoost(entry.id, entry.path, tokens, term)
     if (score > 0) {
-      matches.push({
+      consider({
         type: 'knowledge',
         id: entry.id,
         path: entry.path,
@@ -38,21 +95,32 @@ export const searchIndex = (index: DocBridgeIndexV1, term: string, limit = 20):
   }
 
   for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
-    const hay = `${id} ${owner.path} ${owner.purpose ?? ''} ${owner.group ?? ''}`.toLowerCase()
-    let score = 0
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length * 2
-    }
+    const path = owner.agentDoc ?? owner.path
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ''} ${owner.group ?? ''} ${owner.agentDoc ?? ''} ${owner.humanDoc ?? ''}`.toLowerCase()
+    let score = scoreHay(tokens, hay, 2)
+    score += identityBoost(id, path, tokens, term)
+    // Ownership is primary for routing questions
+    if (wantOwnership) score += 25
+    score += 15 // slight base preference for actionable ownership targets
     if (score > 0) {
-      matches.push({
+      consider({
         type: 'ownership',
         id,
-        path: owner.agentDoc ?? owner.path,
+        path,
         ...(owner.purpose ? { summary: owner.purpose } : {}),
         score,
       })
     }
   }
 
-  return matches.sort((a, b) => b.score - a.score).slice(0, limit)
-}
+  return [...byPath.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    // Tie-break: exact id match, then ownership, then shorter id
+    const aExact = tokens.includes(a.id.toLowerCase()) ? 1 : 0
+    const bExact = tokens.includes(b.id.toLowerCase()) ? 1 : 0
+    if (bExact !== aExact) return bExact - aExact
+    if (a.type === 'ownership' && b.type !== 'ownership') return -1
+    if (b.type === 'ownership' && a.type !== 'ownership') return 1
+    return a.id.localeCompare(b.id)
+  }).slice(0, limit)
+}

package/src/schemas/doc-bridge-index.ts

@@ -21,7 +21,9 @@ export const KnowledgeEntrySchema = z
     type: z.string().min(1).max(128),
     title: z.string().min(1).max(256),
     path: z.string().min(1).max(512),
-    description: z.string().max(1024).optional(),
+    description: z.string().max(2_048).optional(),
+    /** Flattened body excerpt for full-text search (not for display). */
+    body: z.string().max(8_000).optional(),
     links: z.array(z.string().min(1).max(512)).max(64).optional(),
     tags: z.array(z.string().min(1).max(64)).max(32).optional(),
   })

package/src/schemas/json-schemas.ts

@@ -121,7 +121,8 @@ export const DocBridgeIndexV1JsonSchema = {
           type: { type: 'string', minLength: 1, maxLength: 128 },
           title: { type: 'string', minLength: 1, maxLength: 256 },
           path: { type: 'string', minLength: 1, maxLength: 512 },
-          description: { type: 'string', maxLength: 1024 },
+          description: { type: 'string', maxLength: 2048 },
+          body: { type: 'string', maxLength: 8000 },
           links: stringArray(64),
           tags: stringArray(32),
         },

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '0.1.0-alpha.2'
+export const PACKAGE_VERSION = '0.1.0-alpha.3'