export type FormatId = | "html" | "markdown" | "text" | "mdx" | "rst" | "man" | "info" | "help" | "javadoc" | "sphinx" | "doxygen" | "docset" | "json" | "pdf"; /** Format support is independent of publisher identity and source availability. */ export const formatReaders: ReadonlyArray<{ id: FormatId; available: boolean; capability: string; }> = [ { id: "html", available: true, capability: "Static HTML headings, anchors, prose and code; no scripts, DOM execution or site search.", }, { id: "markdown", available: true, capability: "Markdown sections and fenced code; no macro execution.", }, { id: "text", available: true, capability: "Plain text document; no structural symbol index.", }, { id: "mdx", available: true, capability: "Static Markdown/MDX; imports and JSX wrappers omitted, macros retained as inert unsupported text.", }, { id: "rst", available: true, capability: "Basic reStructuredText headings and literal blocks; directives retained, never executed.", }, { id: "man", available: true, capability: "Installed man rendering or static roff headings/prose; macros are never executed by the static reader.", }, { id: "info", available: true, capability: "Installed Info rendering or static Info nodes.", }, { id: "help", available: true, capability: "Installed command help through the local adapter.", }, { id: "javadoc", available: true, capability: "Rendered HTML, bounded ZIP/JAR pages, and standard generated search indexes; no Java or index-script execution.", }, { id: "sphinx", available: true, capability: "Rendered HTML or bounded objects.inv v2 discovery metadata only; inventory has no documentation bodies.", }, { id: "doxygen", available: true, capability: "Rendered HTML plus bounded Doxygen index/tag symbol discovery linked to documentation bodies.", }, { id: "docset", available: true, capability: "Installed Dash/Zeal bundle HTML via its read-only SQLite symbol index; remote tgz expansion is unavailable.", }, { id: "json", available: true, capability: "Structured JSON entries with exact keys, glyphs and compatibility/provenance fields; no schema inference.", }, { id: "pdf", available: true, capability: "PDF text via an already installed pdftotext, fixed arguments and deadline/output limits; tool availability is not guaranteed.", }, ]; export type CatalogSource = { id: string; aliases: readonly string[]; domain: string; home: string; index: string | null; format: FormatId; authority: "publisher" | "standards" | "community" | "host" | "installed"; role: "reference" | "supplemental" | "registry" | "host"; adapter: "upstream" | "local" | "devdocs" | "context7" | "unavailable"; versionSupport: string; description: string; /** Only operator-provided, verified release identity may populate these. */ version?: string; evidence?: string; }; type Row = [ id: string, aliases: string, domain: string, home: string, description: string, ]; const rows: Row[] = [ [ "mdn", "web|javascript|css|html", "web", "https://developer.mozilla.org/en-US/docs/Web/", "Web reference prose; browser compatibility is separate structured data.", ], [ "mdn-content", "", "web", "https://github.com/mdn/content", "Source Markdown contains macros; repository revisions and macro normalization need dedicated support.", ], [ "browser-compat-data", "bcd", "web", "https://raw.githubusercontent.com/mdn/browser-compat-data/main/data.json", "Structured browser and release compatibility, not reference prose.", ], [ "whatwg", "html standard", "standards", "https://html.spec.whatwg.org/", "Living HTML standard; retain section anchors and revision identity.", ], [ "w3c", "web standards", "standards", "https://www.w3.org/TR/", "Normative status and specification revision differ from implementation support.", ], [ "rfc", "rfc editor", "protocols", "https://www.rfc-editor.org/", "RFC status, revisions, obsoletes and supersedes relationships require explicit evidence.", ], [ "wcag", "accessibility|wai", "accessibility", "https://www.w3.org/WAI/WCAG22/quickref/", "WCAG requirements differ from WAI supporting techniques and examples.", ], [ "webdriver-bidi", "bidi", "browser automation", "https://w3c.github.io/webdriver-bidi/", "Protocol revision is not browser implementation support.", ], [ "java", "jdk|java se|javadoc", "java", "https://docs.oracle.com/en/java/javase/", "Java SE API: JDK release, module, package, class and exact member identity.", ], [ "java-specs", "jls|jvms", "java", "https://docs.oracle.com/javase/specs/", "Normative language and VM specifications, not tutorials.", ], [ "dev-java", "dev.java", "java", "https://dev.java/learn/", "Publisher-authored Java tutorials, not normative specifications.", ], [ "maven-central", "maven", "jvm", "https://central.sonatype.com/", "Group/artifact/version discovery; missing -javadoc.jar artifacts remain misses.", ], [ "javadoc-io", "javadoc.io", "jvm", "https://javadoc.io/", "Repository-hosted Javadoc; publisher authority depends on artifact identity.", ], [ "node", "nodejs|node.js", "javascript", "https://nodejs.org/api/", "Node API reference; runtime release must be verified separately.", ], [ "node-learn", "node diagnostics", "javascript", "https://nodejs.org/en/learn", "Learning and operational diagnostics, separate from API reference.", ], [ "typescript", "ts", "typescript", "https://www.typescriptlang.org/docs/", "Compiler-version handbook and language reference.", ], [ "libuv", "", "runtime internals", "https://docs.libuv.org/", "Implementation-specific event loop and API behavior.", ], [ "v8", "", "runtime internals", "https://v8.dev/docs", "Implementation-specific engine behavior and performance.", ], [ "v8-source", "", "runtime internals", "https://github.com/v8/v8/tree/main/docs", "Source documentation; repository revision must be explicit.", ], [ "rust", "rustdoc", "rust", "https://www.rust-lang.org/learn", "Rust language documentation; installed rustdoc is a separate local source.", ], [ "docs-rs", "docs.rs", "rust", "https://docs.rs/", "Crate/version/target identity; rustdoc JSON compatibility and historical availability are not assumed.", ], [ "go", "golang", "go", "https://go.dev/doc/", "Language and toolchain documentation; local go doc is a separate source.", ], [ "pkg-go-dev", "pkg.go.dev", "go", "https://pkg.go.dev/", "Module/package/version and OS/architecture build context require verification.", ], [ "python", "python3", "python", "https://docs.python.org/", "Python language/library releases; rendered Sphinx pages are readable.", ], [ "readthedocs", "read the docs", "python", "https://about.readthedocs.com/", "Hosting platform, not publisher authority; configure the actual project root.", ], [ "cppreference", "cpp|c++|c", "c and c++", "https://en.cppreference.com/", "Community reference, not normative ISO standard; distinguish implementation and library versions.", ], [ "gcc", "compiler manuals", "c and c++", "https://gcc.gnu.org/onlinedocs/", "Compiler manuals are implementation- and release-specific.", ], [ "glibc", "libc", "c and c++", "https://www.gnu.org/software/libc/manual/", "C library manual; installed implementation version is separate evidence.", ], [ "doxygen", "", "c and c++", "https://www.doxygen.nl/manual/", "Configure upstream project pages; Doxygen is a format, not an authority.", ], [ "sqlite", "sqlite3", "databases", "https://sqlite.org/docs.html", "SQLite dialect, library versions, compile options and extensions.", ], [ "postgresql", "postgres", "databases", "https://www.postgresql.org/docs/", "Server-version SQL dialect, extensions and platform requirements.", ], [ "man7", "linux man|linux", "linux", "https://man7.org/linux/man-pages/", "Linux userspace manuals preserve manual section; kernel and distro identity differ.", ], [ "gnu", "gnu manuals", "linux userspace", "https://www.gnu.org/manual/manual.html", "GNU package manuals; package and manual versions need evidence.", ], [ "kernel", "linux kernel", "linux kernel", "https://docs.kernel.org/", "Kernel documentation, not userspace or distribution administration.", ], [ "systemd", "", "linux services", "https://www.freedesktop.org/software/systemd/man/latest/", "System/user scope and implementation versions; latest is not installed-version evidence.", ], [ "freedesktop", "desktop specifications", "desktop standards", "https://specifications.freedesktop.org/", "Desktop specifications differ from installed implementations.", ], [ "archwiki", "arch wiki", "distribution administration", "https://wiki.archlinux.org/", "Community Arch-specific administration; not a cross-distribution assumption.", ], [ "arch-man", "arch manuals", "distribution administration", "https://man.archlinux.org/", "Arch package manuals and distribution-specific release context.", ], [ "arch-news", "arch news", "distribution administration", "https://archlinux.org/news/", "Time-sensitive distribution advisories must retain publication dates.", ], [ "microsoft-learn", "microsoft learn|windows|powershell|dotnet", "windows", "https://learn.microsoft.com/", "Microsoft product documentation; OS, .NET and PowerShell versions differ.", ], [ "win32", "windows win32", "windows", "https://learn.microsoft.com/en-us/windows/win32/", "Win32 OS support, API variants, headers and libraries.", ], [ "win32-api", "windows sdk", "windows", "https://learn.microsoft.com/en-us/windows/win32/api/", "SDK API reference; preserve header, library and minimum supported OS.", ], [ "windows-paths", "windows paths", "paths", "https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file", "Filesystem names versus Win32 namespaces and argument conversion.", ], [ "msys2", "msys2 paths", "paths", "https://www.msys2.org/docs/filesystem-paths/", "Shell/native path and argument conversion, not Windows filesystem rules.", ], [ "bash", "", "shells", "https://www.gnu.org/software/bash/manual/", "Bash syntax and native argument semantics are shell-specific.", ], [ "git", "", "version control", "https://git-scm.com/docs", "Command and recovery semantics depend on installed Git version.", ], [ "jujutsu", "jj", "version control", "https://docs.jj-vcs.dev/latest/", "Revision syntax, bookmarks, working-copy and recovery semantics.", ], [ "github-cli", "gh", "github", "https://cli.github.com/manual/", "CLI command/version and permissions; retrieval never authorizes mutations.", ], [ "github-rest", "github api", "github", "https://docs.github.com/en/rest", "API version, scopes and pagination differ from CLI versions.", ], [ "github", "", "github", "https://docs.github.com/", "Product documentation, not authorization for account changes.", ], [ "nushell", "nu", "shells", "https://www.nushell.sh/book/", "Typed data and installed syntax; command reference and migration intervals differ.", ], [ "nushell-commands", "nu commands", "shells", "https://www.nushell.sh/commands/", "Nushell command reference.", ], [ "nushell-releases", "nu releases", "shells", "https://www.nushell.sh/blog/", "Dated release notes and syntax migrations.", ], [ "mise", "", "tooling", "https://mise.jdx.dev/", "Configuration discovery, trust, CLI, backends and schema.", ], [ "niri", "", "desktop", "https://niri-wm.github.io/niri/", "Compositor config, IPC and installed version support.", ], [ "wezterm", "", "terminal", "https://wezterm.org/config/files.html", "Lua API, CLI and renderer support are version-specific.", ], [ "ast-grep", "sg", "structural search", "https://ast-grep.github.io/", "Structural syntax matching, not semantic references.", ], [ "d2", "", "diagrams", "https://d2lang.com/", "Renderer version, syntax, layout and configuration.", ], [ "d2-source", "", "diagrams", "https://github.com/terrastruct/d2-docs", "Source fallback for rendered pages; repository revision is explicit.", ], [ "mermaid", "", "diagrams", "https://mermaid.js.org/", "Renderer version, syntax, layouts and configuration.", ], [ "mdbook", "", "documentation tooling", "https://rust-lang.github.io/mdBook/", "Version-specific book tooling and configuration.", ], [ "pastel", "", "colors", "https://github.com/sharkdp/pastel", "Source README and installed help; no guessed color conversion.", ], [ "nerd-fonts", "nerdfonts|glyphnames", "icons", "https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/glyphnames.json", "Exact glyph identity, code points and registry revision require a structured JSON reader.", ], [ "cloudflare", "", "hosted platforms", "https://developers.cloudflare.com/", "Product-scoped references, API versions and changing service behavior.", ], [ "google-workspace", "workspace", "hosted platforms", "https://developers.google.com/workspace", "API methods, schemas, scopes, pagination and versions; no account access needed.", ], [ "google-discovery", "google discovery", "hosted platforms", "https://discovery.googleapis.com/discovery/v1/apis", "Structured API discovery metadata; not account data.", ], [ "microsoft-learn-mcp", "learn mcp", "provider retrieval", "https://learn.microsoft.com/en-us/training/support/mcp", "Anonymous search/fetch MCP needs runtime schema discovery; generated-answer tools are excluded.", ], [ "devdocs", "devdocs.io", "cross-domain", "https://devdocs.io/", "Curated docsets with catalog, indexes, release metadata and offline bundles.", ], [ "dash-zeal", "dash|zeal", "cross-domain", "https://kapeli.com/docsets", "Optional feeds/bundles subject to access, attribution and redistribution restrictions.", ], [ "llms-txt", "llms.txt", "cross-domain", "https://llmstxt.org/", "Machine-index convention; register each publisher's scoped index separately.", ], [ "tldr", "tldr-pages", "command examples", "https://github.com/tldr-pages/tldr", "Supplementary platform/language examples, not complete release-compatible reference coverage.", ], [ "context7", "", "cross-domain", "https://context7.com/", "Last-ranked query-scoped fallback; anonymous/keyed mode and version verification are separate.", ], ]; const community = new Set([ "mdn", "mdn-content", "browser-compat-data", "cppreference", "archwiki", "tldr", "nerd-fonts", ]); const hosts = new Set([ "maven-central", "javadoc-io", "docs-rs", "pkg-go-dev", "readthedocs", "dash-zeal", ]); const registries = new Set([ "browser-compat-data", "nerd-fonts", "google-discovery", ]); const indexes: Record = { mise: "https://mise.jdx.dev/llms.txt", "ast-grep": "https://ast-grep.github.io/llms.txt", cloudflare: "https://developers.cloudflare.com/llms.txt", }; export const sourceCatalog: readonly CatalogSource[] = rows.map( ([id, aliases, domain, home, description]) => ({ id, aliases: aliases ? aliases.split("|") : [], domain, home, index: indexes[id] ?? null, format: registries.has(id) ? "json" : id === "dash-zeal" ? "docset" : "html", authority: hosts.has(id) ? "host" : community.has(id) ? "community" : [ "whatwg", "w3c", "wcag", "webdriver-bidi", "rfc", "freedesktop", ].includes(id) ? "standards" : "publisher", role: id === "tldr" ? "supplemental" : registries.has(id) ? "registry" : hosts.has(id) ? "host" : "reference", adapter: id === "devdocs" ? "devdocs" : id === "context7" ? "context7" : ["dash-zeal", "microsoft-learn-mcp"].includes(id) ? "unavailable" : "upstream", versionSupport: "Unknown by default; explicit releases require independently verified source identity. URL paths or HTTP success alone are not evidence.", description, }), ); /** Local discovery is deliberately separate from generic HTTP retrieval. */ export const localSourceCatalog: readonly CatalogSource[] = [ [ "installed-man", "man", "Installed manual sections and owning package versions.", ], ["installed-info", "info", "Installed GNU Info nodes and package versions."], [ "installed-help", "help", "Built-in/subcommand help and PowerShell help through applicable platform conventions.", ], [ "installed-package-docs", "markdown", "Installed READMEs, manuals, examples and package documentation trees.", ], [ "installed-javadoc", "javadoc", "Existing Javadoc archives and generated JVM API docs; never install or build.", ], [ "installed-docsets", "docset", "Existing Dash/Zeal HTML and symbol indexes; no browser application required.", ], [ "installed-sdk-docs", "html", "Application/SDK documentation including Pi via installation metadata or configured roots.", ], ].map(([id, format, description]) => ({ id: id ?? "", aliases: [], domain: "installed documentation", home: "", index: null, format: format as FormatId, authority: "installed", role: "reference", adapter: "local", versionSupport: "Requires installation/package metadata; not inferred from host OS.", description: description ?? "", })); export function sourceCapabilities(source: CatalogSource): { id: string; available: boolean; coverage: "supplemental" | "document"; version: string | null; capability: string | undefined; } { const reader = formatReaders.find((item) => item.id === source.format); return { id: source.id, available: source.adapter === "upstream" && reader?.available === true, coverage: source.role === "supplemental" ? "supplemental" : "document", version: source.version && source.evidence ? source.version : null, capability: source.adapter === "upstream" ? reader?.capability : `Requires ${source.adapter} adapter; availability is determined by parent configuration.`, }; }