@docsworth/cli 0.2.0 → 0.3.0

package/dist/core/repo.d.ts

@@ -10,11 +10,15 @@ export interface Page extends Frontmatter {
     links: string[];
     sha256: string;
     unknownFields: string[];
+    /** Its frontmatter `slug`, if a string: where a docs site serves it (`siteRoute`). Not in the format; read for redaction and lint. */
+    slug?: string;
 }
 export interface InvalidPage {
     path: string;
     /** The `id` field if present and a string, so lint can still report duplicates. */
     id?: string;
+    /** The `slug` field if a string: redaction hides the route it gives the page too. */
+    slug?: string;
     issues: FieldIssue[];
 }
 export interface Repo {

package/dist/core/repo.js

@@ -67,11 +67,13 @@ export function parsePage(path, text) {
     if (!doc.data)
         return { path, issues: [{ field: "(frontmatter)", message: doc.error ?? "missing frontmatter" }] };
     const rawId = typeof doc.data.id === "string" ? doc.data.id : undefined;
+    const slug = typeof doc.data.slug === "string" ? { slug: doc.data.slug } : {};
     const v = validateFrontmatter(doc.data);
     if (!v.ok)
-        return { path, id: rawId, issues: v.issues };
+        return { path, id: rawId, ...slug, issues: v.issues };
     return {
         ...v.value,
+        ...slug,
         path,
         body: doc.body,
         headings: extractHeadings(doc.body),

package/dist/core/schema.d.ts

@@ -5,6 +5,10 @@ export declare const REQUIRED_FIELDS: readonly ["title", "id", "type", "status",
 export declare const OPTIONAL_FIELDS: readonly ["supersedes", "applies_to", "acl", "description"];
 /** Default ACL: anyone with read access to the knowledge repo. */
 export declare const ACL_INTERNAL = "internal";
+/** A team slug, or `internal` (owner_team, acl). */
+export declare const SLUG_RE: RegExp;
+/** A page id: lowercase letters, digits and dashes. */
+export declare const ID_RE: RegExp;
 export declare const FrontmatterSchema: z.ZodObject<{
     title: z.ZodString;
     id: z.ZodString;

package/dist/core/schema.js

@@ -15,22 +15,24 @@ export const REQUIRED_FIELDS = [
 export const OPTIONAL_FIELDS = ["supersedes", "applies_to", "acl", "description"];
 /** Default ACL: anyone with read access to the knowledge repo. */
 export const ACL_INTERNAL = "internal";
-const SLUG = /^[a-z0-9][a-z0-9_-]*$/;
-const ID = /^[a-z0-9][a-z0-9-]*$/;
+/** A team slug, or `internal` (owner_team, acl). */
+export const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/** A page id: lowercase letters, digits and dashes. */
+export const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
 export const FrontmatterSchema = z.object({
     title: z.string().trim().min(1),
-    id: z.string().regex(ID, "lowercase letters, digits and dashes"),
+    id: z.string().regex(ID_RE, "lowercase letters, digits and dashes"),
     type: z.enum(PAGE_TYPES),
     status: z.enum(STATUSES),
     // A bare team slug; the org comes from config (github.org). Never `@user`.
-    owner_team: z.string().regex(SLUG, "a team slug like `platform` (no @, no org)"),
+    owner_team: z.string().regex(SLUG_RE, "a team slug like `platform` (no @, no org)"),
     last_verified: z
         .string()
         .refine((s) => parseDate(s) !== null, "a real calendar date as YYYY-MM-DD"),
     review_every: z.string().regex(DURATION_RE, "a period like 30d, 12w, 6m or 1y"),
-    supersedes: z.array(z.string().regex(ID)).optional(),
+    supersedes: z.array(z.string().regex(ID_RE)).optional(),
     applies_to: z.array(z.string().min(1)).optional(),
-    acl: z.string().regex(SLUG, "`internal` or a team slug").default(ACL_INTERNAL),
+    acl: z.string().regex(SLUG_RE, "`internal` or a team slug").default(ACL_INTERNAL),
     description: z.string().optional(),
 });
 /** Validate raw frontmatter, returning issues keyed by field for the linter. */

package/dist/core/search.d.ts

@@ -20,5 +20,13 @@ export declare class SearchIndex {
     /** Top hits for a query; `accept` filters candidates before ranking (ACL, filters). */
     search(query: string, limit: number, accept?: (index: number) => boolean): Hit[];
 }
+/**
+ * A page's markdown as a reader sees it, to cut snippets from: its words, code as written,
+ * an image as its label, a table's cells (`a | b`); no markup, link targets or raw HTML.
+ * It reads the tree the web app renders from (`parseGfm`), so a snippet cut from it holds
+ * exactly the words the page shows, and never ends inside markup (search's
+ * `snippets: "text"`).
+ */
+export declare function plainText(markdown: string): string;
 /** A ~maxLen window of `body` around the densest run of query terms. */
 export declare function snippet(body: string, query: string, maxLen?: number): string;

package/dist/core/search.js

@@ -1,6 +1,7 @@
 // In-memory BM25 (BM25F-lite: per-field boosts folded into term frequency).
 // The plan says "BM25 first, embeddings later"; this keeps search dependency-free and
 // fast enough for 5,000 pages (scripts/bench-search.ts holds it to p95 < 500 ms).
+import { isTableCell, parseGfm, textIn } from "./gfm.js";
 const STOPWORDS = new Set("a an and are as at be by can do does for from has have how i if in into is it its of on or our should that the their then there this to was we what when where which who why will with you your".split(" "));
 const BOOST = { title: 3, keywords: 3, headings: 2, description: 2, body: 1 };
 const K1 = 1.2;
@@ -74,6 +75,39 @@ export class SearchIndex {
             .slice(0, limit);
     }
 }
+// Blocks whose text a reader sees apart from what's next to them.
+const BLOCKS = new Set(["paragraph", "heading", "item", "block_quote", "code_block", "custom_block", "thematic_break"]);
+/**
+ * A page's markdown as a reader sees it, to cut snippets from: its words, code as written,
+ * an image as its label, a table's cells (`a | b`); no markup, link targets or raw HTML.
+ * It reads the tree the web app renders from (`parseGfm`), so a snippet cut from it holds
+ * exactly the words the page shows, and never ends inside markup (search's
+ * `snippets: "text"`).
+ */
+export function plainText(markdown) {
+    let out = "";
+    const walker = parseGfm(markdown).walker();
+    for (let e = walker.next(); e; e = walker.next()) {
+        const n = e.node;
+        if (!e.entering)
+            continue;
+        if (n.type === "text" || n.type === "code")
+            out += n.literal ?? "";
+        else if (n.type === "code_block")
+            out += ` ${n.literal ?? ""} `;
+        else if (isTableCell(n))
+            out += n.prev ? " | " : " ";
+        // As the web app labels an image (packages/ui/src/markdown.ts): `image: ` and its words,
+        // or its address when it has none, once; what's inside it (an image too) isn't shown.
+        else if (n.type === "image") {
+            out += `image: ${textIn(n) || n.destination || ""}`;
+            walker.resumeAt(n, false);
+        }
+        else if (n.type === "softbreak" || n.type === "linebreak" || BLOCKS.has(n.type))
+            out += " ";
+    }
+    return out.replace(/\s+/g, " ").trim();
+}
 /** A ~maxLen window of `body` around the densest run of query terms. */
 export function snippet(body, query, maxLen = 240) {
     const text = body.replace(/\s+/g, " ").trim();

package/dist/core/serve/server.d.ts

@@ -3,8 +3,7 @@ import { SessionTable, type SessionOptions } from "./sessions.js";
 export declare const DEFAULT_PORT = 4747;
 /** Sent on every response, the static app's included. */
 export declare const SECURITY_HEADERS: Readonly<Record<string, string>>;
-export interface ServeOptions extends Omit<SessionOptions, "knowledgeRoot"> {
-    knowledgeRoot: string;
+export interface ServeOptions extends SessionOptions {
     port: number;
     token: string;
     extensions: ReadonlySet<string>;

package/dist/core/serve/sessions.d.ts

@@ -1,10 +1,9 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Identity } from "../acl.js";
 import { type AuditLog } from "../audit-log.js";
-import { type IdentitySource, KnowledgeService } from "../service.js";
+import { type IdentitySource, KnowledgeService, RepoLoader } from "../service.js";
 export interface SessionOptions {
     root: string;
-    knowledgeRoot: string;
     identity: IdentitySource;
     /** The identity proven at server start, to attribute the first event of each session. */
     who: Identity;
@@ -22,7 +21,8 @@ export declare class SessionTable {
     private readonly sessions;
     /** Sessions being set up: counted against the cap before they have an id. */
     private starting;
-    private watcher;
+    /** One load of the repo for every session; its watcher marks it stale on any change. */
+    readonly loader: RepoLoader;
     private readonly sweeper;
     private readonly max;
     private readonly idleMs;
@@ -30,9 +30,10 @@ export declare class SessionTable {
     get size(): number;
     /** The services of live sessions (tests). */
     services(): KnowledgeService[];
-    private invalidate;
     handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
     private open;
+    /** The session that has had no request in flight for longest, if any. */
+    private idlest;
     /** Close sessions idle longer than the limit, never one with a request in flight. */
     sweep(now?: number): Promise<void>;
     close(): Promise<void>;

package/dist/core/serve/sessions.js

@@ -1,22 +1,54 @@
 import { randomUUID } from "node:crypto";
-import { watch } from "node:fs";
-import { join } from "node:path";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { actorOf } from "../audit-log.js";
 import { auditTransport } from "../mcp/audit-transport.js";
 import { createMcpServer } from "../mcp/server.js";
-import { KnowledgeService, WATCH_SETTLE_MS } from "../service.js";
+import { KnowledgeService, RepoLoader } from "../service.js";
 export const MAX_SESSIONS = 16;
+/** An initialize request is a few hundred bytes; a first request bigger than this isn't one. */
+const MAX_START_BYTES = 64 * 1024;
 export const SESSION_IDLE_MS = 30 * 60_000;
 function json(res, status, body) {
     res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
 }
+const NOT_A_START = { status: 400, error: { code: "invalid", message: "start a session with an initialize request" } };
+/**
+ * A first request's body, if it can start a session: the headers the transport requires,
+ * and exactly one initialize request. Checked before a slot is counted or reclaimed, so a
+ * request the transport would refuse can't close someone's idle session for nothing.
+ */
+async function startBody(req) {
+    const accept = req.headers.accept ?? "";
+    if (!accept.includes("application/json") || !accept.includes("text/event-stream"))
+        return { status: 406, error: { code: "invalid", message: "the client must accept both application/json and text/event-stream" } };
+    if (!(req.headers["content-type"] ?? "").includes("application/json"))
+        return { status: 415, error: { code: "invalid", message: "the body must be application/json" } };
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_START_BYTES)
+            return NOT_A_START;
+        chunks.push(chunk);
+    }
+    let body;
+    try {
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return NOT_A_START;
+    }
+    const only = Array.isArray(body) ? (body.length === 1 ? body[0] : undefined) : body;
+    return isInitializeRequest(only) ? { body } : NOT_A_START;
+}
 export class SessionTable {
     opts;
     sessions = new Map();
     /** Sessions being set up: counted against the cap before they have an id. */
     starting = 0;
-    watcher = null;
+    /** One load of the repo for every session; its watcher marks it stale on any change. */
+    loader;
     sweeper;
     max;
     idleMs;
@@ -24,15 +56,22 @@ export class SessionTable {
         this.opts = opts;
         this.max = opts.maxSessions ?? MAX_SESSIONS;
         this.idleMs = opts.idleMs ?? SESSION_IDLE_MS;
-        // One watcher for every session: a change marks each service dirty, and each reloads
-        // lazily on its next call, never in the middle of a write that is still landing.
-        // It watches pages only. The config and CODEOWNERS (the policy, admins, owners) sit
-        // outside the knowledge root, and every call already stats them: KnowledgeService's
-        // current() reloads when inputsStamp() changes. So a tightened policy applies to an
-        // open session's next call (test/serve.test.ts, "applies a tightened policy").
-        this.watcher = watch(join(opts.root, opts.knowledgeRoot), { recursive: true }, () => this.invalidate());
-        const settle = setTimeout(() => this.invalidate(), WATCH_SETTLE_MS); // see KnowledgeService.watch
-        settle.unref();
+        // One load and one watcher for every session: a change marks the load stale, and the
+        // next call from any session builds a new one, never in the middle of a write that is
+        // still landing. It watches pages only. The config and CODEOWNERS (the policy, admins,
+        // owners) sit outside the knowledge root, and every call already stats them, so a
+        // tightened policy applies to an open session's next call (test/serve.test.ts,
+        // "applies a tightened policy").
+        this.loader = new RepoLoader(opts.root);
+        // A new load is built inside one session's call; every session with nothing in flight
+        // moves onto it now, and a busy one when its last request ends (handle). So however
+        // the repo changes, the sessions hold one load between them, not one each.
+        this.loader.onLoad = () => {
+            for (const s of this.sessions.values())
+                if (s.active === 0)
+                    s.service.release();
+        };
+        this.loader.watch();
         this.sweeper = setInterval(() => void this.sweep(), Math.min(60_000, this.idleMs));
         this.sweeper.unref();
     }
@@ -43,10 +82,6 @@ export class SessionTable {
     services() {
         return [...this.sessions.values()].map((s) => s.service);
     }
-    invalidate() {
-        for (const s of this.sessions.values())
-            s.service.invalidate();
-    }
     async handle(req, res) {
         const sid = req.headers["mcp-session-id"];
         if (sid !== undefined) {
@@ -60,40 +95,68 @@ export class SessionTable {
             finally {
                 session.active--;
                 session.lastUsed = Date.now();
+                if (session.active === 0)
+                    session.service.release();
             }
         }
         if (req.method !== "POST")
-            return json(res, 400, { error: { code: "invalid", message: "start a session with an initialize request" } });
-        // Checked and counted before the first await, so concurrent starts can't pass the cap.
-        if (this.sessions.size + this.starting >= this.max)
-            return json(res, 503, { error: { code: "unavailable", message: `this server already has ${this.max} sessions open; close a tab or wait for idle ones to expire` } });
+            return json(res, 400, { error: NOT_A_START.error });
+        const first = await startBody(req);
+        if (!("body" in first))
+            return json(res, first.status, { error: first.error });
+        // Checked and counted with no await in between, so concurrent starts can't pass the cap.
+        // A full server makes room by closing the session idle longest: a closed tab never
+        // tells the server, so refusing would lock the user out until it expired. Only when
+        // every slot is busy (answering, or still starting) is a new one refused.
+        let reclaimed;
+        if (this.sessions.size + this.starting >= this.max) {
+            reclaimed = this.idlest();
+            if (!reclaimed)
+                return json(res, 503, { error: { code: "unavailable", message: `this server is answering ${this.max} sessions at once; try again in a moment` } });
+            this.sessions.delete(reclaimed.http.sessionId); // out of the table before any await
+        }
+        // This start's slot: counted in `starting` until its session joins the table, then
+        // there instead (never in both, or a start beside a slow first answer finds no room).
         this.starting++;
+        let reserved = true;
+        const joined = () => {
+            if (reserved)
+                this.starting--;
+            reserved = false;
+        };
         try {
-            const session = await this.open();
+            if (reclaimed)
+                await reclaimed.server.close().catch((err) => this.opts.log?.(`closing an idle session failed: ${err.message}`));
+            const session = await this.open(joined);
             try {
-                await session.http.handleRequest(req, res);
+                await session.http.handleRequest(req, res, first.body); // the body is read: hand it over
             }
             finally {
                 // Busy from birth: the session joins the table while this request is still
                 // being answered, so a sweep in between must not take it.
                 session.active--;
                 session.lastUsed = Date.now();
+                if (session.active === 0)
+                    session.service.release(); // as for any request (above)
             }
             // A first request that wasn't an initialize gets the SDK's error and no session.
             if (!session.http.sessionId)
                 await session.server.close();
         }
         finally {
-            this.starting--;
+            joined();
         }
     }
-    async open() {
+    async open(joined) {
         const o = this.opts;
-        const service = new KnowledgeService(o.root, o.identity, o.now);
+        const service = new KnowledgeService(o.root, o.identity, o.now, this.loader);
         const http = new StreamableHTTPServerTransport({
             sessionIdGenerator: randomUUID,
             enableJsonResponse: true,
-            onsessioninitialized: (id) => void this.sessions.set(id, session),
+            onsessioninitialized: (id) => {
+                this.sessions.set(id, session);
+                joined();
+            },
         });
         const transport = o.audit
             ? auditTransport(http, o.audit, () => o.identity.get(), {
@@ -116,15 +179,25 @@ export class SessionTable {
         await server.connect(transport);
         return session;
     }
+    /** The session that has had no request in flight for longest, if any. */
+    idlest() {
+        let found;
+        for (const s of this.sessions.values())
+            if (s.active === 0 && (!found || s.lastUsed < found.lastUsed))
+                found = s;
+        return found;
+    }
     /** Close sessions idle longer than the limit, never one with a request in flight. */
     async sweep(now = Date.now()) {
         const idle = [...this.sessions.values()].filter((s) => s.active === 0 && now - s.lastUsed > this.idleMs);
+        // Out of the table first, so a start can't pick one of these to reclaim as well.
+        for (const s of idle)
+            this.sessions.delete(s.http.sessionId);
         await Promise.all(idle.map((s) => s.server.close()));
     }
     async close() {
         clearInterval(this.sweeper);
-        this.watcher?.close();
-        this.watcher = null;
+        this.loader.close();
         await Promise.all([...this.sessions.values()].map((s) => s.server.close()));
     }
 }

package/dist/core/service.d.ts

@@ -1,9 +1,11 @@
 import { type Identity } from "./acl.js";
+import { type MirrorPage } from "./mirror-view.js";
 import { type NewPageType } from "./new-page.js";
 import { type Policy } from "./policy.js";
 import type { GitHubClient } from "./github.js";
-import { type Page } from "./repo.js";
+import { type Page, type Repo } from "./repo.js";
 import { type PageType } from "./schema.js";
+import { SearchIndex } from "./search.js";
 import { type StaleEntry } from "./stale.js";
 import { type Edit } from "./writes.js";
 export type ToolErrorCode = "not_found" | "forbidden" | "invalid" | "unavailable";
@@ -67,30 +69,105 @@ export declare const DRAFT_MAX_CHARS: number;
 export declare const DRAFT_NAME_ATTEMPTS = 3;
 /** At most this many mirrored pages per search: context, not a second result list. */
 export declare const MIRROR_LIMIT = 3;
+type MirrorView = {
+    pages: MirrorPage[];
+    origin: MirrorPage[];
+    hidden: MirrorPage[];
+    index: SearchIndex;
+};
+type Snapshot = {
+    commit: string | null;
+    dirty: boolean | null;
+    content_sha256: string;
+};
+/**
+ * One load of the repo: the pages, their search index and the served mirror. Never changed
+ * after it is built, except two caches filled on first use: the mirror's views (one per
+ * audience) and the snapshot. A reload builds a new one, so a call that took this one keeps
+ * a consistent view.
+ */
+interface Loaded {
+    readonly repo: Repo;
+    readonly index: SearchIndex;
+    readonly mirror: MirrorPage[];
+    /** Keyed by audience (repo access and teams), so services with any identity can share it. */
+    readonly mirrorViews: Map<string, MirrorView>;
+    /** mtimes of the non-page inputs (config, CODEOWNERS) it was built from. */
+    readonly inputs: string;
+    snap: Snapshot | null;
+}
+/**
+ * Loads the repo and keeps it until something changes, for one service or, in `docsworth
+ * serve`, for every session's service: one copy of the pages and their index however many
+ * tabs are open (a 3,000-page repo took about 50 MB per copy). It owns the one file watcher.
+ * What belongs to a session (its taint, its cached default branch) stays on the service.
+ */
+export declare class RepoLoader {
+    private readonly root;
+    private loaded;
+    private dirty;
+    /** watch() was asked for, and close() hasn't stopped it. */
+    private watching;
+    private watcher;
+    private settle;
+    /** The directory being watched, or to be once it exists (tests read it). */
+    watchedDir: string | null;
+    /** How many times the repo was loaded (tests). */
+    loads: number;
+    /** Called after each load: serve moves its idle sessions onto it, so no old load is kept. */
+    onLoad: (() => void) | null;
+    constructor(root: string);
+    /** The current load: the same object until a change is seen, then a new one, built once. */
+    current(): Loaded;
+    /** The newest load, without looking for changes. */
+    latest(): Loaded | null;
+    /** Has a change been seen that the next call will load (tests). */
+    get pending(): boolean;
+    private load;
+    /** Config and CODEOWNERS live outside the watched knowledge root; stat them per call. */
+    private inputsStamp;
+    /** Load again on the next call. */
+    invalidate(): void;
+    /** Mark the load stale on any change under the knowledge root. */
+    watch(): void;
+    /** Watch `repo`'s knowledge root, in place of whatever was watched before. */
+    private follow;
+    close(): void;
+    private stop;
+}
 export declare class KnowledgeService {
     private readonly root;
     private readonly identity;
     private readonly now;
+    private readonly loader;
+    /** A loader this service made is its own to close; a shared one belongs to its owner. */
+    private readonly ownsLoader;
+    private loaded;
     private repo;
     private index;
-    private dirty;
-    /** mtimes of the non-page inputs (config, CODEOWNERS) the loaded repo was built from. */
-    private inputs;
-    private watcher;
-    private watchedDir;
-    private settle;
     private defaultBranch;
     /** Mirrored pages, when mirror.serve is on; one search index per audience (views). */
     private mirror;
-    private readonly mirrorViews;
+    private mirrorViews;
     /** Team ACLs whose content this session has seen (write-path taint check). */
     private readonly tainted;
     /** The random end of a drafted page's id and file name (replaced in tests). */
     private draftSuffix;
-    constructor(root: string, identity: IdentitySource, now?: () => Date);
+    /** `loader`: a load shared with other services (`docsworth serve`'s sessions); else its own. */
+    constructor(root: string, identity: IdentitySource, now?: () => Date, loader?: RepoLoader);
+    /** Load the repo again now. */
     reload(): void;
-    /** Config and CODEOWNERS live outside the watched knowledge root; stat them per call. */
-    private inputsStamp;
+    /**
+     * Point at the loader's newest load, letting go of an older one. Only while no call of
+     * this service is running: `docsworth serve` calls it for a session with no request in
+     * flight, so an idle tab doesn't keep a whole old copy of the repo alive.
+     */
+    release(): void;
+    /** Take a new load, and drop what this service cached from the last one. */
+    private adopt;
+    /** The watched directory and a pending reload live on the loader (tests read them here). */
+    private get watchedDir();
+    private get dirty();
     /**
      * The mirrored pages `who` may see, each with links to the ones they can't see
      * redacted (and to repo pages they can't see: a wiki page can link to one by its URL),
@@ -98,23 +175,19 @@ export declare class KnowledgeService {
      * a page outside it. One per audience (the caller's teams), rebuilt on reload.
      */
     private mirrorView;
-    /** Reload on the next call. `docsworth serve` runs one watcher for all its sessions' services. */
+    /** Reload on the next call. */
     invalidate(): void;
     /** Mark the index dirty on any change under the knowledge root. */
     watch(): void;
+    /** Stops this service's own watcher; a shared loader's is its owner's to stop. */
     close(): void;
     private current;
-    private snap;
     /**
      * The knowledge actually being served: the checkout's HEAD and whether the served files
      * differ from it, plus a hash of the loaded config, ownership and pages. Refreshed after
      * every reload, so an audit event names the snapshot its answer came from.
      */
-    snapshot(): {
-        commit: string | null;
-        dirty: boolean | null;
-        content_sha256: string;
-    };
+    snapshot(): Snapshot;
     /** Every page id, team and applies_to tag the repo uses: what an audited argument may record. */
     knownValues(): {
         ids: Set<string>;
@@ -141,11 +214,14 @@ export declare class KnowledgeService {
         applies_to?: string;
         include_stale?: boolean;
         limit?: number;
+        /** "text": snippets cut from the page as a reader sees it (the web app); else markdown. */
+        snippets?: "markdown" | "text";
     }): Promise<{
         results: SearchResult[];
         excluded: Excluded[];
         mirrored?: MirroredHit[];
         note?: string;
+        snippets?: "text";
     }>;
     read(args: {
         id: string;
@@ -228,8 +304,15 @@ export declare class KnowledgeService {
         writes_off?: string | undefined;
         pro: string[];
     }>;
-    /** Counts over the caller's visible pages, by team, with what is due soon and what is stale. */
-    uiOverview(): Promise<{
+    /**
+     * Counts over the caller's visible pages, by team, with what is due soon and what is stale.
+     * `list_limit` keeps a big repo's overview short: the first of each list, the most pressing
+     * first, with `due_soon_total` and `stale_total`. Only the pages returned are named, so only
+     * those taint the session; the counts above the lists name no page.
+     */
+    uiOverview(args?: {
+        list_limit?: number;
+    }): Promise<{
         as_of: string;
         totals: {
             pages: number;
@@ -248,6 +331,9 @@ export declare class KnowledgeService {
         }[];
         due_soon: PageSummary[];
         stale: StaleEntry[];
+        due_soon_total: number;
+        stale_total: number;
+        skipped_files: number;
     }>;
     /**
      * A page as `read` shows it, with `links`: the repo path and id of each visible page it
@@ -295,9 +381,15 @@ export declare class KnowledgeService {
      * Visible pages and the links between them. A link to a page the caller can't see is no
      * edge; `has_restricted_links` says a page has one, exactly as its `read` text shows a
      * placeholder for it, so the graph reveals nothing `read` doesn't.
+     *
+     * `max_nodes` keeps a big repo drawable: past it, the most-linked pages (links between
+     * visible pages only; ties by id) and the links among them. `total` says how many it
+     * chose from, and `teams` how many visible pages each team has, a count that names no
+     * page. Only the returned pages are named, so only those taint the session.
      */
     uiGraph(args?: {
         owner_team?: string;
+        max_nodes?: number;
     }): Promise<{
         nodes: {
             id: string;
@@ -316,6 +408,11 @@ export declare class KnowledgeService {
             from: string;
             to: string;
         }[];
+        total: number;
+        teams: {
+            team: string;
+            pages: number;
+        }[];
     }>;
     /** What every write needs first: the policy, a live identity, a GitHub repo. */
     private writeIdentity;
@@ -373,3 +470,4 @@ export declare class KnowledgeService {
         last_verified: string;
     }>;
 }
+export {};