@aiwayds/dsh-topics-memory 0.6.0

package/lib/okf.d.ts

@@ -0,0 +1,112 @@
+/**
+ * OKF v0.2 concept-document model for the Topic profile (ADR 0001).
+ *
+ * A Topic is a markdown file with YAML frontmatter plus a body. The Topic
+ * profile fixes the extension keys (`depends`, `open_questions`, `impact`)
+ * and the conventional body headings (`# Conclusion`, `# Recommendations`);
+ * the OKF provenance/trust/lifecycle families pass through untouched.
+ *
+ * `depends` entries are bundle-relative paths (`topics/<slug>.md`) so the
+ * file stays OKF-conformant and cross-linkable; graph helpers convert
+ * between paths and slugs (ADR 0005).
+ *
+ * @module okf
+ */
+export type TopicStatus = 'draft' | 'stable' | 'deprecated';
+export interface SourceEntry {
+    id?: string;
+    resource: string;
+    title?: string;
+    author?: string;
+    usage_count?: number;
+    last_modified?: string;
+}
+export interface TrustStamp {
+    by: string;
+    at: string;
+}
+export interface TopicFrontmatter {
+    type: string;
+    title: string;
+    description?: string;
+    tags: string[];
+    /** Bundle-relative paths: `topics/<slug>.md`. */
+    depends: string[];
+    open_questions: string[];
+    impact: string[];
+    status: TopicStatus;
+    generated: TrustStamp;
+    verified?: TrustStamp;
+    stale_after?: string;
+    sources?: SourceEntry[];
+    /** Producer-defined extras — preserved on round-trip per OKF §4.1. */
+    [extra: string]: unknown;
+}
+export interface TopicDoc {
+    fm: TopicFrontmatter;
+    body: string;
+}
+export declare class OkfError extends Error {
+    name: string;
+}
+/** Filenames with defined meaning in a bundle; never usable as topic slugs. */
+export declare const RESERVED_FILES: ReadonlySet<string>;
+/**
+ * Parse a Topic document. Throws OkfError on structural violations
+ * (missing frontmatter, non-mapping, missing type/title).
+ */
+export declare function parseTopicDoc(raw: string): TopicDoc;
+/** Serialize a Topic document with a deterministic frontmatter field order. */
+export declare function serializeTopicDoc(doc: TopicDoc): string;
+/** Split a body into `# Heading` sections: [{heading, text}] in order. */
+export declare function splitSections(body: string): {
+    heading: string;
+    text: string;
+}[];
+/** The text under a given `# Heading`, or undefined when absent. */
+export declare function sectionOf(body: string, heading: string): string | undefined;
+/** First non-empty line of a text block — the 结论精句 used in digests. */
+export declare function firstParagraph(text: string): string;
+/** Replace or append a `# Heading` section, preserving other content and order. */
+export declare function setSection(body: string, heading: string, text: string): string;
+/**
+ * Slug from a title: latin lowercased, CJK preserved, spaces/punctuation
+ * collapse to dashes. Never empty (falls back to `topic`) and never a
+ * reserved filename.
+ */
+export declare function slugify(title: string): string;
+/** `topics/foo.md` → `foo`; anything else unchanged. */
+export declare function pathToSlug(path: string): string;
+/** `foo` → `topics/foo.md`. */
+export declare function slugToPath(slug: string): string;
+/** Bundle-relative paths of `depends` entries that point at topics. */
+export declare function dependsSlugs(fm: {
+    depends: readonly string[];
+}): string[];
+export interface IndexEntry {
+    slug: string;
+    title: string;
+    description?: string;
+    status: TopicStatus;
+    tags: string[];
+}
+/** Render the auto-generated OKF `index.md` (progressive disclosure, §Bundle). */
+export declare function renderIndex(entries: IndexEntry[]): string;
+/** Loose ISO-8601 instant check (OKF requires explicit UTC offsets in spec, kept tolerant). */
+export declare function isIsoInstant(s: string): boolean;
+/**
+ * Normalize one link target to a topic slug, or undefined when the target is
+ * not a bundle-internal topic reference. Accepts `slug`, `slug.md`,
+ * `topics/slug`, `[[slug#heading]]`, `[[slug|alias]]`.
+ */
+export declare function normalizeLinkTarget(target: string): string | undefined;
+/**
+ * Topic slugs referenced from a body: `[[wikilinks]]` (with optional
+ * `#heading` / `|alias`) plus markdown links pointing at bundle paths.
+ * These are the human-authored edges alongside `depends` — both feed the
+ * retrieval graph walk and the backlinks index.
+ */
+export declare function bodyLinkSlugs(body: string): string[];
+/** The conventional profile headings, for validators and tooling. */
+export declare const CONCLUSION_HEADING = "Conclusion";
+export declare const RECOMMENDATIONS_HEADING = "Recommendations";

package/lib/okf.js

@@ -0,0 +1,279 @@
+/**
+ * OKF v0.2 concept-document model for the Topic profile (ADR 0001).
+ *
+ * A Topic is a markdown file with YAML frontmatter plus a body. The Topic
+ * profile fixes the extension keys (`depends`, `open_questions`, `impact`)
+ * and the conventional body headings (`# Conclusion`, `# Recommendations`);
+ * the OKF provenance/trust/lifecycle families pass through untouched.
+ *
+ * `depends` entries are bundle-relative paths (`topics/<slug>.md`) so the
+ * file stays OKF-conformant and cross-linkable; graph helpers convert
+ * between paths and slugs (ADR 0005).
+ *
+ * @module okf
+ */
+import { parseYaml, stringifyYaml, YamlError } from "./yaml.js";
+export class OkfError extends Error {
+    name = 'OkfError';
+}
+/** Filenames with defined meaning in a bundle; never usable as topic slugs. */
+export const RESERVED_FILES = new Set(['index.md', 'spec.md']);
+const PROFILE_HEADINGS = ['conclusion', 'recommendations'];
+function asStringArray(v) {
+    if (v === undefined || v === null)
+        return [];
+    if (!Array.isArray(v))
+        throw new OkfError('expected a list');
+    return v.map((x) => {
+        if (typeof x !== 'string')
+            throw new OkfError('list entries must be strings');
+        return x;
+    });
+}
+function asTrust(v, field) {
+    if (v === null || v === undefined || typeof v !== 'object') {
+        throw new OkfError(`frontmatter.${field} must be an object {by, at}`);
+    }
+    const o = v;
+    if (typeof o.by !== 'string' || o.by === '' || typeof o.at !== 'string' || o.at === '') {
+        throw new OkfError(`frontmatter.${field} requires string "by" and "at"`);
+    }
+    return { by: o.by, at: o.at };
+}
+function asStatus(v) {
+    if (v === undefined || v === null || v === '')
+        return 'draft';
+    if (v === 'draft' || v === 'stable' || v === 'deprecated')
+        return v;
+    throw new OkfError(`frontmatter.status must be draft|stable|deprecated, got "${String(v)}"`);
+}
+/**
+ * Parse a Topic document. Throws OkfError on structural violations
+ * (missing frontmatter, non-mapping, missing type/title).
+ */
+export function parseTopicDoc(raw) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (m === null)
+        throw new OkfError('document must start with a --- frontmatter block');
+    let fmRaw;
+    try {
+        fmRaw = parseYaml(m[1]);
+    }
+    catch (e) {
+        if (e instanceof YamlError)
+            throw new OkfError(`frontmatter: ${e.message}`);
+        throw e;
+    }
+    if (typeof fmRaw.type !== 'string' || fmRaw.type === '') {
+        throw new OkfError('frontmatter.type is required (OKF §4.1)');
+    }
+    const title = typeof fmRaw.title === 'string' && fmRaw.title !== '' ? fmRaw.title : fmRaw.type;
+    const tags = asStringArray(fmRaw.tags);
+    const depends = asStringArray(fmRaw.depends);
+    const open_questions = asStringArray(fmRaw.open_questions);
+    const impact = asStringArray(fmRaw.impact);
+    const generated = 'generated' in fmRaw ? asTrust(fmRaw.generated, 'generated') : { by: 'unknown', at: new Date(0).toISOString() };
+    const fm = {
+        type: fmRaw.type,
+        title,
+        tags,
+        depends,
+        open_questions,
+        impact,
+        status: asStatus(fmRaw.status),
+        generated,
+    };
+    if (typeof fmRaw.description === 'string' && fmRaw.description !== '')
+        fm.description = fmRaw.description;
+    if ('verified' in fmRaw && fmRaw.verified !== null && fmRaw.verified !== undefined)
+        fm.verified = asTrust(fmRaw.verified, 'verified');
+    if (typeof fmRaw.stale_after === 'string' && fmRaw.stale_after !== '')
+        fm.stale_after = fmRaw.stale_after;
+    if (Array.isArray(fmRaw.sources)) {
+        fm.sources = fmRaw.sources.map((s) => {
+            if (s === null || typeof s !== 'object' || typeof s.resource !== 'string') {
+                throw new OkfError('frontmatter.sources entries require a string "resource" (OKF §5.1)');
+            }
+            return s;
+        });
+    }
+    // Preserve unknown producer-defined keys verbatim (OKF §4.1 extensions).
+    const known = new Set(['type', 'title', 'description', 'tags', 'depends', 'open_questions', 'impact', 'status', 'generated', 'verified', 'stale_after', 'sources']);
+    for (const [k, v] of Object.entries(fmRaw)) {
+        if (!known.has(k))
+            fm[k] = v;
+    }
+    return { fm, body: m[2] };
+}
+/** Serialize a Topic document with a deterministic frontmatter field order. */
+export function serializeTopicDoc(doc) {
+    const fm = doc.fm;
+    const out = {
+        type: fm.type,
+        title: fm.title,
+    };
+    if (fm.description !== undefined)
+        out.description = fm.description;
+    out.tags = fm.tags;
+    out.depends = fm.depends;
+    out.open_questions = fm.open_questions;
+    out.impact = fm.impact;
+    out.status = fm.status;
+    out.generated = { by: fm.generated.by, at: fm.generated.at };
+    if (fm.verified !== undefined)
+        out.verified = { by: fm.verified.by, at: fm.verified.at };
+    if (fm.stale_after !== undefined)
+        out.stale_after = fm.stale_after;
+    if (fm.sources !== undefined && fm.sources.length > 0)
+        out.sources = fm.sources;
+    for (const [k, v] of Object.entries(fm)) {
+        if (!(k in out))
+            out[k] = v;
+    }
+    return `---\n${stringifyYaml(out)}---\n${doc.body}`;
+}
+/** Split a body into `# Heading` sections: [{heading, text}] in order. */
+export function splitSections(body) {
+    const sections = [];
+    let current;
+    for (const line of body.split('\n')) {
+        const m = /^# (.+)$/.exec(line);
+        if (m !== null) {
+            if (current !== undefined)
+                sections.push({ heading: current.heading, text: current.text.join('\n').trim() });
+            current = { heading: m[1].trim(), text: [] };
+        }
+        else if (current !== undefined) {
+            current.text.push(line);
+        }
+    }
+    if (current !== undefined)
+        sections.push({ heading: current.heading, text: current.text.join('\n').trim() });
+    return sections;
+}
+/** The text under a given `# Heading`, or undefined when absent. */
+export function sectionOf(body, heading) {
+    const hit = splitSections(body).find((s) => s.heading.toLowerCase() === heading.toLowerCase());
+    return hit === undefined ? undefined : hit.text;
+}
+/** First non-empty line of a text block — the 结论精句 used in digests. */
+export function firstParagraph(text) {
+    for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (t !== '')
+            return t;
+    }
+    return '';
+}
+/** Replace or append a `# Heading` section, preserving other content and order. */
+export function setSection(body, heading, text) {
+    const sections = splitSections(body);
+    const idx = sections.findIndex((s) => s.heading.toLowerCase() === heading.toLowerCase());
+    if (idx >= 0) {
+        sections[idx] = { heading: sections[idx].heading, text };
+    }
+    else {
+        sections.push({ heading, text });
+    }
+    return sections.map((s) => `# ${s.heading}\n\n${s.text}`).join('\n\n') + '\n';
+}
+/**
+ * Slug from a title: latin lowercased, CJK preserved, spaces/punctuation
+ * collapse to dashes. Never empty (falls back to `topic`) and never a
+ * reserved filename.
+ */
+export function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .normalize('NFKC')
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^\p{Script=Latin}\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Cyrillic}\p{Nd}-]/gu, '')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/g, '');
+    if (slug === '' || RESERVED_FILES.has(`${slug}.md`))
+        return 'topic';
+    return slug;
+}
+/** `topics/foo.md` → `foo`; anything else unchanged. */
+export function pathToSlug(path) {
+    const m = /^topics\/(.+)\.md$/.exec(path);
+    return m === null ? path : m[1];
+}
+/** `foo` → `topics/foo.md`. */
+export function slugToPath(slug) {
+    return `topics/${slug}.md`;
+}
+/** Bundle-relative paths of `depends` entries that point at topics. */
+export function dependsSlugs(fm) {
+    return fm.depends.map(pathToSlug);
+}
+/** Render the auto-generated OKF `index.md` (progressive disclosure, §Bundle). */
+export function renderIndex(entries) {
+    const lines = [
+        '# Topic Index',
+        '',
+        `Auto-generated by dsh-topics-memory — do not edit. ${entries.length} topic${entries.length === 1 ? '' : 's'}.`,
+        '',
+    ];
+    for (const e of entries.sort((a, b) => a.slug.localeCompare(b.slug))) {
+        const desc = e.description !== undefined && e.description !== '' ? ` — ${e.description}` : '';
+        lines.push(`- [${e.title}](topics/${e.slug}.md) \`${e.status}\`${desc}`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** Loose ISO-8601 instant check (OKF requires explicit UTC offsets in spec, kept tolerant). */
+export function isIsoInstant(s) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(s);
+}
+const WIKILINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+const MD_LINK = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+/**
+ * Normalize one link target to a topic slug, or undefined when the target is
+ * not a bundle-internal topic reference. Accepts `slug`, `slug.md`,
+ * `topics/slug`, `[[slug#heading]]`, `[[slug|alias]]`.
+ */
+export function normalizeLinkTarget(target) {
+    let t = target.trim();
+    if (t === '' || t.includes('://') || t.startsWith('#') || t.startsWith('mailto:'))
+        return undefined;
+    t = t.split('#')[0].trim();
+    if (t === '')
+        return undefined;
+    if (t.endsWith('.md'))
+        t = t.slice(0, -3);
+    if (t.startsWith('./'))
+        t = t.slice(2);
+    if (t.startsWith('topics/'))
+        t = t.slice('topics/'.length);
+    if (t === '' || t.includes('/') || t.includes(':'))
+        return undefined;
+    if (RESERVED_FILES.has(`${t}.md`))
+        return undefined;
+    return t;
+}
+/**
+ * Topic slugs referenced from a body: `[[wikilinks]]` (with optional
+ * `#heading` / `|alias`) plus markdown links pointing at bundle paths.
+ * These are the human-authored edges alongside `depends` — both feed the
+ * retrieval graph walk and the backlinks index.
+ */
+export function bodyLinkSlugs(body) {
+    const out = new Set();
+    for (const m of body.matchAll(WIKILINK)) {
+        const slug = normalizeLinkTarget(m[1]);
+        if (slug !== undefined)
+            out.add(slug);
+    }
+    for (const m of body.matchAll(MD_LINK)) {
+        const slug = normalizeLinkTarget(m[1]);
+        if (slug !== undefined)
+            out.add(slug);
+    }
+    out.delete('');
+    return [...out];
+}
+/** The conventional profile headings, for validators and tooling. */
+export const CONCLUSION_HEADING = 'Conclusion';
+export const RECOMMENDATIONS_HEADING = 'Recommendations';

package/lib/onboard.d.ts

@@ -0,0 +1,205 @@
+/**
+ * `/topics onboard` — an a/b/c configuration wizard that walks a new user
+ * through the five decisions that matter (storage mode, GitHub repo, distill
+ * model, injection budget, auto-observe) one command at a time.
+ *
+ * Design (ADR 0009):
+ *  - one invocation = one step: the wizard renders the current question with
+ *    lettered options; the answer arrives as the next invocation's argument
+ *    (`/topics onboard b`). Works unchanged on every surface (tui, web, feishu,
+ *    headless one-shots) because it never needs intra-turn interactivity.
+ *  - answers accumulate in a pending batch; only the final confirm step
+ *    writes settings — quitting midway leaves the config untouched.
+ *  - the step machine is pure (`applyAnswer` / `renderStep`), so tests drive
+ *    it without spawning `gh`; the handler injects the login detector.
+ *
+ * @module onboard
+ */
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { TopicsService } from './service.ts';
+import { type TopicsConfigValue } from './config.ts';
+/** CamelCase → dash-display, shared with /topics config rendering. */
+export declare function displayKey(key: string): string;
+export type StepId = 'mode' | 'repo' | 'distill' | 'inject' | 'observe' | 'confirm' | 'done';
+export interface OnboardState {
+    step: StepId;
+    /** Answers so far; only written to settings at the confirm step. */
+    pending: Partial<TopicsConfigValue>;
+    /** Whether the user picked GitHub mode (adds the repo step). */
+    pathHasRepo: boolean;
+}
+export type MutateFn = (ops: readonly {
+    op: 'set';
+    path: string[];
+    value: unknown;
+}[]) => Promise<void>;
+export type GithubLoginDetector = () => Promise<string | undefined>;
+/**
+ * Suggested remote repo name. Deliberately NOT `dsh-topics-memory`: that is
+ * the plugin's own source repository, and the default data repo must never
+ * collide with it (ADR 0002/0009).
+ */
+export declare const DEFAULT_TOPICS_REPO = "dsh-topics-data";
+export declare function freshState(): OnboardState;
+/** Render the current step against live config overlaid with pending answers. */
+export declare function renderStep(state: OnboardState, cfg: TopicsConfigValue): string;
+/**
+ * Pure step machine: consume one answer, return the next state. The caller
+ * intercepts control answers (quit) and confirm-write before calling this.
+ */
+export declare function applyAnswer(state: OnboardState, answer: string, cfg: TopicsConfigValue): {
+    state: OnboardState;
+    error?: string;
+};
+/** Settings ops for the pending batch, in stable CONFIG_KEYS order. */
+export declare function confirmOps(pending: Partial<TopicsConfigValue>): {
+    op: 'set';
+    path: string[];
+    value: unknown;
+}[];
+/**
+ * `gh api user --jq .login` with a hard timeout; undefined on any failure
+ * (gh missing, not logged in, slow). Never throws.
+ */
+export declare function detectGithubLogin(timeoutMs?: number): Promise<string | undefined>;
+export interface AskOptionShape {
+    label: string;
+    description?: string;
+}
+export interface AskItemShape {
+    id: string;
+    question: string;
+    detail?: string;
+    header?: string;
+    options?: AskOptionShape[];
+}
+export interface AskAnswerItemShape {
+    id: string;
+    selected: string[];
+    custom?: string;
+}
+export interface AskServiceShape {
+    ask(request: {
+        questions: AskItemShape[];
+        agent?: unknown;
+        signal?: AbortSignal;
+    }): Promise<{
+        answers: AskAnswerItemShape[];
+    }>;
+}
+export type AskServiceResolver = () => AskServiceShape | undefined;
+/** Structural view of the dsh llm service used for distill-route pickers. */
+export interface LlmDirectoryShape {
+    /** Live routes only (providers with a registered adapter), in registration order. */
+    listProviders(): readonly {
+        id: string;
+        name: string;
+    }[];
+    /** Advisory catalog; an unlisted model id may still be usable. */
+    listModels(provider: string): Promise<readonly {
+        provider: string;
+        id: string;
+        name: string;
+        description?: string;
+    }[]>;
+    /** Pure in-memory exact-route check; rejects with coded errors (e.g. NO_ADAPTER). */
+    resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<unknown>;
+}
+/**
+ * Ordered llm candidates for the distill pickers: session-scoped capture
+ * first (the instance this session's own loop streams through), apply-time
+ * root second. Consumers pick with `pickLlmDirectory` — the first candidate
+ * whose `listProviders()` is non-empty wins — so neither source's emptiness
+ * shadows the other.
+ */
+export type LlmDirectoryResolver = () => readonly (LlmDirectoryShape | undefined)[];
+/** Where the candidate walk for the distill pickers landed. */
+export type LlmDirectoryPick = {
+    kind: 'ok';
+    llm: LlmDirectoryShape;
+} | {
+    kind: 'empty-directory';
+} | {
+    kind: 'no-instance';
+};
+/**
+ * First candidate with a non-empty live route table wins. Distinguishes
+ * 「有实例但列表空」(service present, zero enabled providers) from
+ * 「均不可用」(nothing reachable) so each gets its own user hint.
+ */
+export declare function pickLlmDirectory(candidates: readonly (LlmDirectoryShape | undefined)[]): LlmDirectoryPick;
+/** One-line why-not for the distill pick panels; undefined when usable. */
+export declare function llmDirectoryNotice(pick: LlmDirectoryPick): string | undefined;
+/** Build one ask() closure that rides the invocation's agent/signal context. */
+export declare function makePanel(ask: AskServiceShape, agent: unknown, signal: AbortSignal | undefined): (questions: AskItemShape[]) => Promise<AskAnswerItemShape[]>;
+interface InvocationAgentShape {
+    id?: unknown;
+    session?: {
+        id?: unknown;
+    };
+}
+/** provider model（空格）或 provider/model（斜杠）；model 本身可含斜杠。 */
+export declare function parseDistillInput(raw: string): {
+    provider: string;
+    model: string;
+} | {
+    error: string;
+};
+/** Blank item = the UI's "skipped" encoding: keep the current value. */
+export declare function isAnswered(a: AskAnswerItemShape | undefined): a is AskAnswerItemShape;
+/**
+ * Two dependent panels — provider first, then that provider's models — so the
+ * model list can come from the chosen provider's catalog. Answers run through
+ * `resolveModelInfo` before entering the pending batch: NO_ADAPTER blocks and
+ * re-asks (bounded), any other rejection (model outside the advisory catalog,
+ * possibly still usable) warns but allows. Returns undefined when the user
+ * skips or blanks the panel (keep current).
+ */
+export declare function askDistillRoute(llm: LlmDirectoryShape, panel: (questions: AskItemShape[]) => Promise<AskAnswerItemShape[]>, cfg: {
+    distillProvider: string;
+    distillModel: string;
+}, maxAttempts?: number): Promise<{
+    provider: string;
+    model: string;
+    unknownModel: boolean;
+} | undefined>;
+/**
+ * Single-panel variant behind `/topics set distill-provider|distill-model`:
+ * one question, current value shown, blank answer = keep. Validation mirrors
+ * the wizard (`askDistillRoute`): a provider pick must sit in the live route
+ * table (the NO_ADAPTER equivalent — blocked, bounded re-ask); a model pick
+ * runs through `resolveModelInfo` — NO_ADAPTER blocks, any other failure
+ * warns but allows (model outside the advisory catalog, possibly still
+ * usable). Returns the picked value (plus the warning when a failed check was
+ * allowed through), or undefined on skip/blank.
+ */
+export declare function askDistillSingle(llm: LlmDirectoryShape, panel: (questions: AskItemShape[]) => Promise<AskAnswerItemShape[]>, key: 'distill-provider' | 'distill-model', cfg: {
+    distillProvider: string;
+    distillModel: string;
+}, maxAttempts?: number): Promise<{
+    value: string;
+    warning?: string;
+} | undefined>;
+/**
+ * The interactive flow: storage mode, then the distill route as two dependent
+ * panels (provider → that provider's models), then a batched panel (repo when
+ * GitHub mode, inject tier, observe), then a confirm panel whose detail lists
+ * exactly what will be written. A closed panel or a skipped question never
+ * writes. Hosts without the llm directory never enter here (the handler gates
+ * on it and falls back to the typed wizard).
+ */
+export declare function runInteractiveOnboard(service: TopicsService, mutate: MutateFn, ask: AskServiceShape, detectLogin: GithubLoginDetector, agent: InvocationAgentShape | undefined, signal: AbortSignal | undefined, llm: LlmDirectoryShape): Promise<CommandResult>;
+/**
+ * The `/topics onboard <args>` handler. One instance per command registration —
+ * wizard state lives in the closure, so tests get a fresh wizard per
+ * buildTopicsCommand() and concurrent surfaces don't share progress.
+ *
+ * Primary path is the native ask-user seam when BOTH providers are present:
+ * `resolveAsk()` (TUI panel, web composer, feishu card — whichever surface
+ * owns the slot, with dsh-ask-router optionally fanning out) and a usable
+ * `resolveLlm()` candidate (the first with a non-empty live route table,
+ * feeding the distill provider/model panels). Either one missing — bare
+ * hosts, no UI, no model route — falls back to the typed wizard.
+ */
+export declare function createOnboardHandler(service: TopicsService, mutate: MutateFn, detectLogin?: GithubLoginDetector, resolveAsk?: AskServiceResolver, resolveLlm?: LlmDirectoryResolver): (args: string[], invocation: CommandInvocation) => Promise<CommandResult>;
+export {};