@agentskit/doc-bridge 1.11.2 → 1.12.0

package/src/findings/report.ts

@@ -4,7 +4,7 @@ import type { Evidence, FindingStatus, KnowledgeDiagnostic } from '../schemas/kn
  * The canonical finding, as the rest of the ecosystem consumes it.
  *
  * `Finding` and `SEVERITY_ORDER` mirror `@agentskit/core/finding`, which is an optional peer:
- * Code Review, AKOS and dashboards read this shape, so a Doc Bridge diagnostic reported in it
+ * Code Review and dashboards read this shape, so a Doc Bridge diagnostic reported in it
  * needs no parser of its own. A test imports the real package and asserts that what is emitted
  * here is assignable to it and that the severities are drawn from the real order.
  *

package/src/fixes/proposals.ts

@@ -3,6 +3,7 @@ import { basename, dirname, extname, join, relative, resolve, sep } from 'node:p
 
 import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
 import { FixProposalV1Schema, type FixProposalV1 } from '../schemas/knowledge.js'
+import { createIgnoreFilter, type IgnoreFilter } from '../lib/ignore-filter.js'
 import { containedPath } from '../safety/repository.js'
 
 export type FixProposalOptions = {
@@ -55,10 +56,11 @@ const makeProposal = (root: string, options: FixProposalOptions, changes: readon
   return FixProposalV1Schema.parse({ ...draft, contentHash: contentHashForArtifactV1(draft) })
 }
 
-const walkMarkdown = (root: string, directory = root): string[] => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+const walkMarkdown = (root: string, directory = root, ignored: IgnoreFilter = createIgnoreFilter(root)): string[] => readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
   if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') return []
   const path = join(directory, entry.name)
-  if (entry.isDirectory()) return walkMarkdown(root, path)
+  if (ignored.isIgnored(path, entry.isDirectory())) return []
+  if (entry.isDirectory()) return walkMarkdown(root, path, ignored)
   return entry.isFile() && ['.md', '.mdx'].includes(extname(entry.name).toLowerCase()) ? [relative(root, path).split(sep).join('/')] : []
 })
 

package/src/gates/run-gates.ts

@@ -92,7 +92,7 @@ export const runGate = (
     return {
       id,
       ok: false,
-      message: `${result.ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index. Add them to safety.exclude.`,
+      message: `${result.ignored.length} indexed path(s) are ignored by Git, so a clean checkout builds a different index. Rebuild the index (scans skip ignored paths) or add them to safety.exclude.`,
       expected: 'every indexed path is committed',
       actual: sample.join(', '),
     }

package/src/index-builder/human-adapters/core.ts

@@ -37,12 +37,15 @@ export const optionString = (
 }
 
 export const parseFrontmatter = (raw: string): Record<string, string> => {
-  if (!raw.startsWith('---\n')) return {}
-  const end = raw.indexOf('\n---', 4)
+  // Windows-authored (or git autocrlf-checked-out) Markdown commonly uses CRLF;
+  // normalize before matching so frontmatter isn't silently dropped there.
+  const normalized = raw.includes('\r\n') ? raw.replace(/\r\n/g, '\n') : raw
+  if (!normalized.startsWith('---\n')) return {}
+  const end = normalized.indexOf('\n---', 4)
   if (end === -1) return {}
 
   const out: Record<string, string> = {}
-  for (const line of raw.slice(4, end).split('\n')) {
+  for (const line of normalized.slice(4, end).split('\n')) {
     const match = /^([A-Za-z0-9_-]+):\s*(.+?)\s*$/.exec(line)
     if (match?.[1] && match[2]) out[match[1]] = match[2].replace(/^['"]|['"]$/g, '')
   }
@@ -89,7 +92,10 @@ export const scanMarkdownDocs = (
     const canonical = realpathSync.native(abs)
     const fileRelative = relative(projectRoot, canonical)
     if (isAbsolute(fileRelative) || fileRelative === '..' || fileRelative.startsWith(`..${sep}`)) continue
-    const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ''))
+    // Both sides must be toPosix'd before stripping the prefix: `abs` is native-separator
+    // (backslashes on Windows), so comparing it raw against a toPosix'd `absRoot` never
+    // matches there, silently leaving relToHumanRoot as the full absolute path.
+    const relToHumanRoot = toPosix(abs).replace(`${toPosix(absRoot)}/`, '')
     const raw = readBoundedText(abs, budget)
     if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue
     out.push({

package/src/lib/ignore-filter.ts

@@ -0,0 +1,151 @@
+/**
+ * Which files a repository scan may see.
+ *
+ * A committed index is only reproducible while it is a function of committed (or at least
+ * non-ignored) content. Build output — `.next/`, `.source/`, generated API docs, files that a dev
+ * server writes such as `next-env.d.ts` — exists on one machine and not on the next, so every walk
+ * that feeds the index honours the repository's ignore rules in addition to its own excludes.
+ *
+ * Inside a Git work tree the answer comes from Git itself (`git ls-files --cached --others
+ * --exclude-standard`), which applies nested `.gitignore` files, `.git/info/exclude`, and the
+ * user's global excludes exactly as `git status` does, and still lists tracked files that happen to
+ * match an ignore rule. Outside Git (a tarball, a CI cache, Git not installed) the `.gitignore`
+ * files on disk are applied with the same semantics, one directory at a time.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+import ignore, { type Ignore } from 'ignore'
+
+export type IgnoreFilterMode = 'git' | 'gitignore'
+
+export type IgnoreFilter = {
+  /** `git` when Git answered for this root, `gitignore` for the on-disk fallback. */
+  readonly mode: IgnoreFilterMode
+  /** True when `absolutePath` (a file, or a directory when `isDirectory`) must not be scanned. */
+  readonly isIgnored: (absolutePath: string, isDirectory: boolean) => boolean
+}
+
+const toPosix = (value: string): string => value.split(sep).join('/')
+
+const canonical = (path: string): string => {
+  try {
+    return realpathSync.native(resolve(path))
+  } catch {
+    return resolve(path)
+  }
+}
+
+/** Path of `candidate` below `root` in POSIX form, or undefined when it is outside `root`. */
+const below = (root: string, candidate: string): string | undefined => {
+  const rel = relative(root, candidate)
+  if (rel === '') return ''
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) return undefined
+  return toPosix(rel)
+}
+
+const gitVisibleFiles = (root: string): readonly string[] | undefined => {
+  try {
+    const inside = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    if (inside !== 'true') return undefined
+    const output = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: 256 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    // Paths are relative to `cwd`. A nested repository shows up as `name/`; its files stay hidden.
+    return output.split('\0').filter(Boolean)
+  } catch {
+    return undefined
+  }
+}
+
+const gitFilter = (root: string, canonicalRoot: string, visible: readonly string[]): IgnoreFilter => {
+  const files = new Set(visible.filter((path) => !path.endsWith('/')))
+  const directories = new Set<string>([''])
+  for (const file of visible) {
+    let parent = file
+    for (;;) {
+      const slash = parent.lastIndexOf('/')
+      if (slash === -1) break
+      parent = parent.slice(0, slash)
+      if (directories.has(parent)) break
+      directories.add(parent)
+    }
+  }
+  return {
+    mode: 'git',
+    isIgnored: (absolutePath, isDirectory) => {
+      const rel = below(root, resolve(absolutePath)) ?? below(canonicalRoot, canonical(absolutePath))
+      if (rel === undefined) return false
+      return isDirectory ? !directories.has(rel) : !files.has(rel)
+    },
+  }
+}
+
+const gitignoreFilter = (root: string): IgnoreFilter => {
+  const rules = new Map<string, Ignore | undefined>()
+  const rulesFor = (directory: string): Ignore | undefined => {
+    if (rules.has(directory)) return rules.get(directory)
+    const file = join(directory, '.gitignore')
+    let matcher: Ignore | undefined
+    if (existsSync(file)) {
+      try {
+        matcher = ignore().add(readFileSync(file, 'utf8'))
+      } catch {
+        matcher = undefined
+      }
+    }
+    rules.set(directory, matcher)
+    return matcher
+  }
+  const ignoredCache = new Map<string, boolean>()
+  const isIgnored = (absolutePath: string, isDirectory: boolean): boolean => {
+    const target = resolve(absolutePath)
+    const rel = below(root, target)
+    if (rel === undefined || rel === '') return false
+    const key = `${isDirectory ? 'd' : 'f'}:${rel}`
+    const cached = ignoredCache.get(key)
+    if (cached !== undefined) return cached
+    // A path is ignored when an ancestor directory is ignored, or when the nearest applicable rule
+    // in any `.gitignore` between the root and its parent matches it (deeper files win).
+    const parent = dirname(target)
+    let result = parent !== root && below(root, parent) !== undefined ? isIgnored(parent, true) : false
+    if (!result) {
+      let decided: boolean | undefined
+      let directory = root
+      const segments = below(root, parent)?.split('/').filter(Boolean) ?? []
+      for (let index = 0; index <= segments.length; index += 1) {
+        if (index > 0) directory = join(directory, segments[index - 1] as string)
+        const matcher = rulesFor(directory)
+        if (!matcher) continue
+        const local = toPosix(relative(directory, target)) + (isDirectory ? '/' : '')
+        const verdict = matcher.test(local)
+        if (verdict.ignored) decided = true
+        else if (verdict.unignored) decided = false
+      }
+      result = decided ?? false
+    }
+    ignoredCache.set(key, result)
+    return result
+  }
+  return { mode: 'gitignore', isIgnored }
+}
+
+/**
+ * Build the filter for one scan root. Call once per walk: the Git listing reflects the working
+ * tree at that moment, so a long-lived watcher rebuilds it on every rescan.
+ */
+export const createIgnoreFilter = (root: string): IgnoreFilter => {
+  const base = resolve(root)
+  const canonicalRoot = canonical(root)
+  const visible = gitVisibleFiles(canonicalRoot)
+  return visible ? gitFilter(base, canonicalRoot, visible) : gitignoreFilter(base)
+}

package/src/lib/walk.ts

@@ -1,6 +1,7 @@
 import { lstatSync, readdirSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { createIgnoreFilter } from './ignore-filter.js'
 import { toPosix } from './paths.js'
 
 const DEFAULT_SKIP = new Set(['node_modules', '.git', 'dist', 'coverage', '.doc-bridge'])
@@ -12,12 +13,19 @@ export const walkFiles = (
     readonly extensions?: readonly string[]
     readonly skipDirs?: ReadonlySet<string>
     readonly maxFiles?: number
+    /**
+     * Skip what the repository ignores (`.gitignore`, `.git/info/exclude`, global excludes) on top
+     * of `skipDirs`. On by default; only walks of non-repository input, such as an agent memory
+     * directory, turn it off.
+     */
+    readonly respectIgnore?: boolean
   },
 ): string[] => {
   const extensions = opts?.extensions ?? ['.md']
   const skip = opts?.skipDirs ?? DEFAULT_SKIP
   const out: string[] = []
   const visited = new Set<string>()
+  const ignored = opts?.respectIgnore === false ? undefined : createIgnoreFilter(root)
 
   const visit = (dir: string) => {
     let canonicalDir: string
@@ -45,12 +53,12 @@ export const walkFiles = (
       }
       if (st.isSymbolicLink()) continue
       if (st.isDirectory()) {
-        if (skip.has(name)) continue
+        if (skip.has(name) || ignored?.isIgnored(abs, true)) continue
         visit(abs)
         continue
       }
       if (!st.isFile()) continue
-      if (extensions.some((ext) => name.endsWith(ext))) {
+      if (extensions.some((ext) => name.endsWith(ext)) && !ignored?.isIgnored(abs, false)) {
         if (out.length >= (opts?.maxFiles ?? DEFAULT_MAX_FILES)) {
           throw new Error(`Documentation corpus exceeds the ${opts?.maxFiles ?? DEFAULT_MAX_FILES} file limit.`)
         }

package/src/memory/ingest.ts

@@ -20,7 +20,7 @@ const ingestMarkdownDir = (
 ): MemoryCandidateV1[] => {
   if (!existsSync(dir)) return []
 
-  return walkFiles(dir, { extensions: ['.md', '.mdc'] }).map((abs) => {
+  return walkFiles(dir, { extensions: ['.md', '.mdc'], respectIgnore: false }).map((abs) => {
     const rel = relativePath(root, abs)
     const raw = readFileSync(abs, 'utf8')
     const id = slugFromPath(rel)

package/src/report/html.ts

@@ -424,7 +424,7 @@ const findingMatches=(finding)=>{const query=state.query.toLowerCase();return(!q
 const findingScope=(finding)=>data.view?.diagnosticGroup?.[finding.id]?.[0]||(()=>{const ids=[...(finding.entityIds||[])];(finding.relationIds||[]).forEach((id)=>{const relation=relationById.get(id);if(relation)ids.push(relation.from,relation.to)});return ids.map(groupFor).sort()[0]||"repository"})();
 const findingGroups=(findings)=>{const groups=new Map();findings.forEach((finding)=>{const scope=findingScope(finding),key=[scope,finding.code,finding.status,finding.severity].join("|"),group=groups.get(key)||{key,scope,code:finding.code,status:finding.status,severity:finding.severity,findings:[]};group.findings.push(finding);groups.set(key,group)});return[...groups.values()].sort((left,right)=>right.findings.length-left.findings.length||left.code.localeCompare(right.code)||left.key.localeCompare(right.key))};
 const renderFinding=(finding)=>"<article class=\"finding\" id=\""+esc("diagnostic-"+finding.id.replace(/[^A-Za-z0-9_-]+/g,"-"))+"\"><div class=\"finding-head\"><h3>"+esc(finding.code)+"</h3><span><span class=\"tag "+esc(finding.severity)+"\">"+esc(finding.severity)+"</span> <span class=\"tag\">"+esc(finding.status)+"</span></span></div><p>"+esc(finding.message)+"</p>"+(finding.evidence.length?"<ul>"+finding.evidence.slice(0,4).map((item)=>"<li>"+esc(item.path+(item.lineStart?":"+item.lineStart:"")+(item.context?" — "+item.context:""))+"</li>").join("")+"</ul>":"")+(finding.remediation?"<p><strong>Next check:</strong> "+esc(finding.remediation)+"</p>":"")+"</article>";
-const renderFindings=()=>{let findings=data.diagnostics.filter(findingMatches);if(state.lens==="risks")findings=findings.filter((finding)=>finding.severity==="error"||finding.severity==="warn");if(state.lens==="evidence")findings=findings.filter((finding)=>finding.evidence.length);if(state.lens==="drift")findings=findings.filter((finding)=>finding.status!=="confirmed");const itemLabel=state.lens==="evidence"?"evidence checks":"findings",groups=findingGroups(findings),active=groups.find((group)=>group.key===state.findingGroup);if(!active){state.findingGroup=null;state.findingPage=0}syncHash();const selected=active||null,pageSize=40,pageCount=selected?Math.ceil(selected.findings.length/pageSize):0,page=Math.max(0,Math.min(state.findingPage,Math.max(0,pageCount-1))),start=page*pageSize;document.querySelector("#finding-count").textContent=findings.length+" "+itemLabel+" · "+groups.length+" groups";document.querySelector("#findings").innerHTML=findings.length?"<div class=\"finding-groups\">"+groups.map((group)=>"<article class=\"finding-group\"><div class=\"finding-head\"><h3>"+esc(group.code)+"</h3><span><span class=\"tag "+esc(group.severity)+"\">"+esc(group.severity)+"</span> <span class=\"tag\">"+esc(group.status)+"</span></span></div><p><strong>"+group.findings.length+"</strong> "+itemLabel+" · "+esc(groupById.get(group.scope)?.name||group.scope)+"</p><p>"+esc(group.findings[0].message)+"</p><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(group.key)+"\" aria-expanded=\""+String(selected?.key===group.key)+"\">Inspect group</button></article>").join("")+"</div>"+(selected?"<div class=\"finding-detail\"><div class=\"finding-head\"><h3>"+esc(selected.code)+" · "+esc(groupById.get(selected.scope)?.name||selected.scope)+"</h3><span class=\"subtle\">"+selected.findings.length+" "+itemLabel+"</span></div>"+selected.findings.slice(start,start+pageSize).map(renderFinding).join("")+"<div class=\"finding-actions\"><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(selected.key)+"\" data-finding-page=\""+(page-1)+"\" "+(page===0?"disabled":"")+">Previous</button><span class=\"subtle\">Showing "+(start+1)+"–"+Math.min(start+pageSize,selected.findings.length)+" of "+selected.findings.length+" · page "+(page+1)+"/"+pageCount+"</span><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(selected.key)+"\" data-finding-page=\""+(page+1)+"\" "+(page+1>=pageCount?"disabled":"")+">Next</button></div></div>":""):"<p class=\"empty\">No "+itemLabel+" match the current lens and filters.</p>"};
+const renderFindings=()=>{let findings=data.diagnostics.filter(findingMatches);if(state.lens==="risks")findings=findings.filter((finding)=>finding.severity==="error"||finding.severity==="warn");if(state.lens==="evidence")findings=findings.filter((finding)=>finding.evidence.length);if(state.lens==="drift")findings=findings.filter((finding)=>finding.status!=="confirmed");const itemLabel=state.lens==="evidence"?"evidence checks":"findings",groups=findingGroups(findings),active=groups.find((group)=>group.key===state.findingGroup);if(!active){state.findingGroup=null;state.findingPage=0}syncHash();const selected=active||null,pageSize=40,pageCount=selected?Math.ceil(selected.findings.length/pageSize):0,page=Math.max(0,Math.min(state.findingPage,Math.max(0,pageCount-1))),start=page*pageSize;document.querySelector("#finding-count").textContent=findings.length+" "+itemLabel+" · "+groups.length+" groups";document.querySelector("#findings").innerHTML=findings.length?"<div class=\"finding-groups\">"+groups.map((group)=>"<article class=\"finding-group\"><div class=\"finding-head\"><h3>"+esc(group.code)+"</h3><span><span class=\"tag "+esc(group.severity)+"\">"+esc(group.severity)+"</span> <span class=\"tag\">"+esc(group.status)+"</span></span></div><p><strong>"+group.findings.length+"</strong> "+itemLabel+" · "+esc(groupById.get(group.scope)?.name||group.scope)+"</p><p>"+esc(group.findings[0].message)+"</p><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(group.key)+"\" aria-expanded=\""+String(selected?.key===group.key)+"\">Inspect group</button></article>").join("")+"</div>"+(selected?"<div class=\"finding-detail\"><div class=\"finding-head\"><h3>"+esc(selected.code)+" · "+esc(groupById.get(selected.scope)?.name||selected.scope)+"</h3><span class=\"subtle\">"+selected.findings.length+" "+itemLabel+"</span></div>"+selected.findings.slice(start,start+pageSize).map(renderFinding).join("")+"<div class=\"finding-actions\"><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(selected.key)+"\" data-finding-page=\""+(page - 1)+"\" "+(page===0?"disabled":"")+">Previous</button><span class=\"subtle\">Showing "+(start+1)+"–"+Math.min(start+pageSize,selected.findings.length)+" of "+selected.findings.length+" · page "+(page+1)+"/"+pageCount+"</span><button class=\"tab\" type=\"button\" data-finding-group=\""+esc(selected.key)+"\" data-finding-page=\""+(page+1)+"\" "+(page+1>=pageCount?"disabled":"")+">Next</button></div></div>":""):"<p class=\"empty\">No "+itemLabel+" match the current lens and filters.</p>"};
 const renderCoverage=()=>{document.querySelector("#coverage-list").innerHTML=(data.coverage||[]).map((entry)=>{const width=entry.status==="complete"?100:entry.status==="partial"?55:12;return"<div class=\"coverage-row\"><div><b>"+esc(entry.analyzer)+"</b><br><span class=\"subtle\">"+esc(entry.scope)+"</span></div><div class=\"bar\"><i class=\""+(entry.status==="complete"?"":entry.status==="partial"?"partial":"none")+"\" style=\"width:"+width+"%\"></i></div><div>"+esc(entry.status)+"</div></div>"}).join("")||"<p class=\"empty\">No coverage metadata.</p>"};
 const deferFindings=()=>{if(findingsLoaded())return;const actionable=data.actionableCount??data.diagnosticCount??0,confirmed=data.confirmedCount??0;document.querySelector("#finding-count").textContent=actionable+" actionable findings · "+confirmed+" confirmed checks available on demand";document.querySelector("#findings").innerHTML="<div class=\"empty\"><p>Findings stay out of the first paint so large repositories remain responsive. Confirmed checks are evidence, not issues.</p><button id=\"load-findings\" class=\"tab\" type=\"button\">Load findings</button></div>"};
 const scopePrompt=()=>{if((state.level==="module"||state.level==="file")&&!state.selected){document.querySelector("#map-note").textContent="Select an app or package to inspect this level.";document.querySelector("#graph").innerHTML="<text x=\"500\" y=\"270\" text-anchor=\"middle\" class=\"subtle\">Select an app or package to expand this view.</text>"}};

package/src/safety/repository.ts

@@ -3,6 +3,8 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import { minimatch } from 'minimatch'
 
+import { createIgnoreFilter } from '../lib/ignore-filter.js'
+
 export const DEFAULT_SAFETY_EXCLUDES = ['**/.git/**', '**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.doc-bridge/**', '**/.next/**', '**/out/**', '**/.turbo/**', '**/.svelte-kit/**', '**/.mcpb-build/**', '**/.mcpb-output/**', '**/.env', '**/.env.*', '**/*secret*', '**/*credential*', '**/*.pem', '**/*.key'] as const
 
 export type SafeWalkOptions = {
@@ -12,6 +14,11 @@ export type SafeWalkOptions = {
   readonly maxBytes?: number
   readonly maxTimeMs?: number
   readonly maxMemoryMb?: number
+  /**
+   * Skip what the repository ignores (Git ignore rules, or `.gitignore` files outside Git) in
+   * addition to `exclude`, so build output never reaches the index. Defaults to true.
+   */
+  readonly respectIgnore?: boolean
 }
 
 export type SafeWalkResult = {
@@ -43,6 +50,7 @@ export const safeWalkFiles = (root: string, options: SafeWalkOptions = {}): Safe
   let reason: string | undefined
   const started = Date.now()
   const matchesExclude = (path: string): boolean => excludes.some((pattern) => minimatch(path, pattern, { dot: true }))
+  const ignored = options.respectIgnore === false ? undefined : createIgnoreFilter(projectRoot)
   const visit = (directory: string): void => {
     if (reason) return
     if (options.maxTimeMs !== undefined && Date.now() - started >= options.maxTimeMs) { reason = `Repository scan exceeded the ${options.maxTimeMs} ms time limit.`; return }
@@ -56,6 +64,7 @@ export const safeWalkFiles = (root: string, options: SafeWalkOptions = {}): Safe
       let stats
       try { stats = lstatSync(absolute) } catch { continue }
       if (stats.isSymbolicLink()) continue
+      if (ignored?.isIgnored(absolute, stats.isDirectory())) continue
       if (stats.isDirectory()) { visit(absolute); if (reason) return; continue }
       if (!stats.isFile() || (extensions.length > 0 && !extensions.some((extension) => name.endsWith(extension)))) continue
       if (files.length >= (options.maxFiles ?? 10_000)) { reason = `Repository scan exceeded the ${options.maxFiles ?? 10_000} file limit.`; return }

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.11.2'
+export const PACKAGE_VERSION = '1.12.0'

package/docs/DOGFOOD-ROUND2.md

@@ -1,147 +0,0 @@
----
-title: Dogfood round 2
-description: Validation evidence from the second published Doc Bridge alpha.
----
-
-# 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/docs/DOGFOOD-ROUND3.md

@@ -1,79 +0,0 @@
----
-title: Dogfood round 3
-description: Validation evidence from the third published Doc Bridge alpha.
----
-
-# Dogfood round 3 — `@agentskit/doc-bridge@0.1.0-alpha.3`
-
-**Date:** 2026-07-09  
-**npm:** `alpha` → `0.1.0-alpha.3` · `latest` still `0.1.0-alpha.1`
-
-## Scoreboard
-
-| Repo | Install | Ver | K | Handoffs | Gate | Ranking | Ask | Retrieve |
-|------|---------|-----|---|----------|------|---------|-----|----------|
-| **agentskit** | `pnpm add -Dw` ✅ | 0.1.0-alpha.3 | 25 | 24 | ✅ 24 humanDoc | `core` #1 (683) ✅ | ownership core ✅ | ✅ soft, 8 chunks |
-| **agentskit-os** | `npx` (store issue) ✅ | 0.1.0-alpha.3 | 170 | 92 | ✅ | `os-core` #1 (689) ✅ | ownership os-core ✅ | ✅ 8 chunks |
-| **playbook** | `pnpm add -D` ✅ | 0.1.0-alpha.3 | 127 | 81 | ✅ okf | OKF pattern #1 ✅ | pattern ownership ✅ | ✅ |
-| **registry** | `--legacy-peer-deps` ⚠️ | 0.1.0-alpha.3 | 36 | 36 | ✅ | `docs-chat` #1 (593) ✅ | docs-chat ✅ | ✅ |
-
-## Round-2 issues — validation
-
-| Item (R2) | Status | Evidence |
-|-----------|--------|----------|
-| Exact id ranking | **Fixed** | agentskit `search core` → best=`core` not angular |
-| ask wrong package | **Fixed** | “change the core package?” → ownership core |
-| Notes truncated | **Fixed** | full purpose sentences on core / os-core |
-| Full-text search | **Improved** | `search documentation` → 20 matches (was 0) |
-| Federation 404 hard-fail | **Fixed** | retrieve exit 0, no error, local chunks only |
-| Peer install friction | **Improved** | no peer warning on agentskit; registry still needs legacy-peer-deps |
-| Text UX | **Fixed** | multi-line `[ownership] id score=` format |
-| Path dedupe | **OK** | top lists are unique ownership rows |
-| AKOS humanDoc sparse | **Still open** | os-core handoff has no `humanDoc` (product docs thin) |
-| pnpm store AKOS | **Still open** | environment; npx works |
-| `latest` on old alpha | **Still open** | publish hygiene |
-
-## Sample outputs (alpha.3)
-
-### agentskit — ranking
-
-```json
-{ "term": "core", "best": "core", "top": ["core:683", "angular:27", "ink:27"] }
-```
-
-### agentskit — handoff
-
-```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",
-  "notes": ["Stable TypeScript contracts (Adapter, Tool, Memory, Retriever, Skill, Runtime) + `createChatController` + primitives. Target: <10 KB gzipped, zero runtime deps."]
-}
-```
-
-### agentskit-os — ranking
-
-```json
-{ "best": "os-core", "top": ["os-core:689", "command-palette:36", "os-blob:36"] }
-```
-
-### registry — ranking
-
-```json
-{ "best": "docs-chat", "top": ["docs-chat:593", "agency-brief-generator:15"] }
-```
-
-## Remaining improvements (lower urgency)
-
-1. **AKOS humanDoc coverage** — enrich for-agents frontmatter `humanDoc` or map product Fumadocs more densely (content work more than code).
-2. **npm install without legacy-peer-deps** on registry — may still need peerOptional tuning vs npm ERESOLVE; document install flags.
-3. **HTML entities in notes** — `&lt;10 KB` from source MD; optional decode on index.
-4. **AKOS lockfile install path** — fix local pnpm store / commit published dep version.
-5. **CI wire-up** — `docs:bridge:gate` on each consumer after merge of dogfood branches.
-6. **Publish tags** — keep `latest` free of prereleases or retag intentionally.
-
-## Verdict
-
-**alpha.3 is a successful dogfood pass.** P0/P1 product issues from round 2 are validated fixed on published package across monorepo + playbook + registry. Remaining items are polish, content, or consumer-side install/CI.