kontexta 4.3.1

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/02-api.md

@@ -0,0 +1,169 @@
+---
+title: API Documentation
+group: Getting Started
+order: 2
+icon: 🔌
+---
+
+# Special Blocks
+
+kontexta Publish supports several special markdown blocks that enhance your documentation with interactive elements.
+
+## Mermaid Diagrams
+
+Create diagrams using Mermaid syntax. Wrap your diagram code in a fenced code block with the `mermaid` language tag.
+
+### Example: Flowchart
+
+```mermaid
+graph TD
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Process A]
+  B -->|No| D[Process B]
+  C --> E[End]
+  D --> E
+```
+
+### Example: Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant App
+  participant Server
+  User->>App: Click button
+  App->>Server: API call
+  Server-->>App: Response
+  App-->>User: Update UI
+```
+
+### Features
+
+- **Zoom** — Use the zoom buttons or Ctrl+wheel to zoom in/out
+- **Fullscreen** — Click the fullscreen button or press Ctrl+Enter
+- **Auto-render** — Mermaid diagrams are automatically rendered on page load
+
+## API Endpoints
+
+Document your API endpoints using the `endpoints` block. Each endpoint is rendered as an interactive card.
+
+### Example
+
+```endpoints
+- method: GET
+  path: /api/v1/docs
+  badge: stable
+  description: List all available documentation pages
+  headers:
+    Authorization: Bearer token required
+    Accept: application/json
+  statusCodes:
+    "200": Success — returns list of pages
+    "401": Unauthorized — invalid or missing token
+  request: |
+    GET /api/v1/docs HTTP/1.1
+    Host: example.com
+    Authorization: Bearer <token>
+  response: |
+    HTTP/1.1 200 OK
+    Content-Type: application/json
+    
+    {
+      "pages": [
+        {"title": "Overview", "slug": "overview"},
+        {"title": "API", "slug": "api"}
+      ]
+    }
+```
+
+### Endpoint Card Features
+
+- **Method badge** — Color-coded HTTP method (GET, POST, PUT, DELETE, etc.)
+- **Interactive modal** — Click any endpoint card to see full details
+- **Status codes** — Document expected responses
+- **Request/Response** — Show example request and response bodies
+
+## Glossary Terms
+
+Build a searchable glossary using the `glossary` block.
+
+### Example
+
+```glossary
+- term: kontexta
+  definition: A local-first knowledge and context engine for AI coding agents.
+- term: vault
+  definition: The storage location for markdown knowledge files, typically in ~/.local/share/kontexta/knowledge/.
+- term: MCP
+  definition: Model Context Protocol — a standard for connecting AI models to external data sources.
+- term: FTS5
+  definition: Full-Text Search version 5, SQLite's built-in full-text search engine.
+```
+
+### Glossary Features
+
+- **Alphabetical display** — Terms are displayed in alphabetical order
+- **Searchable** — Terms appear in the search results
+- **Clickable** — Click any term to jump to its definition
+
+## Frontmatter
+
+Every markdown file can include frontmatter at the top to control how it's rendered.
+
+### Available Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `title` | string | Yes | Display title for the page |
+| `group` | string | No | Navigation group name (defaults to folder name) |
+| `order` | number | No | Sort order within the group (lower = first) |
+| `icon` | string | No | Emoji or icon to display in navigation |
+
+### Example
+
+```yaml
+---
+title: My Page
+group: Documentation
+order: 5
+icon: 📄
+---
+```
+
+## Code Blocks
+
+Standard markdown code blocks are supported with syntax highlighting.
+
+### JavaScript Example
+
+```javascript
+function greet(name) {
+  return `Hello, ${name}!`;
+}
+
+console.log(greet('World'));
+```
+
+### TypeScript Example
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function createUser(id: number, name: string, email: string): User {
+  return { id, name, email };
+}
+```
+
+### Bash Example
+
+```bash
+# Install kontexta publish
+npm install -g kxta-publish
+
+# Generate docs
+kxta-publish --folder docs --output index.html
+```

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/03-improvements.md

@@ -0,0 +1,90 @@
+---
+title: Improvements & Roadmap
+group: Getting Started
+order: 3
+icon: 🚀
+---
+
+# Improvements & Roadmap
+
+kontexta Publish is designed to be extensible and continuously improving. Here's what's planned and how you can contribute.
+
+## Current Capabilities
+
+kontexta Publish already provides:
+
+- ✅ Single-file static site generation
+- ✅ Three-pane responsive layout
+- ✅ Client-side search with type filtering
+- ✅ Mermaid diagram rendering with zoom/fullscreen
+- ✅ API endpoint documentation with interactive modals
+- ✅ Glossary term management
+- ✅ Dark/light theme toggle
+- ✅ Hash-based routing and scroll-spy
+- ✅ kontexta theme tokens and typography
+
+## Planned Improvements
+
+### Phase 1: Enhanced Navigation
+
+- **Breadcrumb navigation** — Show current location in the document hierarchy
+- **Previous/Next links** — Navigate between documents sequentially
+- **Document versioning** — Support multiple versions of documentation
+- **Multi-language support** — i18n for international documentation
+
+### Phase 2: Search Enhancements
+
+- **Fuzzy search** — Tolerate typos and partial matches
+- **Search filters** — Filter by folder, date, or tags
+- **Search analytics** — Track popular searches and missing content
+- **External search integration** — Connect to Algolia or similar services
+
+### Phase 3: Rendering Improvements
+
+- **Custom themes** — Allow users to define their own color schemes
+- **Plugin system** — Extend rendering with custom block types
+- **Math rendering** — Support LaTeX equations via KaTeX
+- **PDF export** — Generate printable PDF versions
+
+### Phase 4: Developer Experience
+
+- **Hot reload** — Instant preview during development
+- **CLI improvements** — More configuration options
+- **CI/CD integration** — Automated documentation builds
+- **Documentation** — Comprehensive user guide and examples
+
+## Contributing
+
+We welcome contributions! Here's how you can help:
+
+### Reporting Issues
+
+- Use the GitHub issue tracker
+- Include steps to reproduce
+- Mention your browser and OS version
+- Provide screenshots if applicable
+
+### Submitting Pull Requests
+
+1. Fork the repository
+2. Create a feature branch
+3. Write tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request with a clear description
+
+### Code Style
+
+- TypeScript with strict mode
+- ESLint with recommended rules
+- Prettier for formatting
+- Vitest for testing
+
+## Feedback
+
+We'd love to hear from you! Share your thoughts on:
+
+- What features would you like to see?
+- Are there any bugs you've encountered?
+- How are you using kontexta Publish?
+
+Your feedback helps us prioritize improvements and make kontexta Publish better for everyone.

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/04-glossary.md

@@ -0,0 +1,55 @@
+---
+title: Glossary
+group: Getting Started
+order: 4
+icon: 📖
+---
+
+# Glossary
+
+Key terms and concepts used throughout kontexta Publish documentation.
+
+```glossary
+- term: kontexta
+  definition: "A local-first knowledge and context engine for AI coding agents. Stores markdown notes in a git-versioned vault, indexes them with SQLite + FTS5, and exposes them through a Model Context Protocol (MCP) server."
+- term: vault
+  definition: "The storage location for markdown knowledge files. By default located at ~/.local/share/kontexta/knowledge/ on Linux, ~/Library/Application Support/kontexta/knowledge/ on macOS, or %APPDATA%\\kontexta\\knowledge\\ on Windows."
+- term: MCP
+  definition: "Model Context Protocol — an open standard for connecting AI models to external data sources, tools, and services. Enables AI agents to search, read, write, and organize knowledge files."
+- term: FTS5
+  definition: "Full-Text Search version 5, SQLite's built-in full-text search engine. Used by kontexta to index and search markdown files efficiently."
+- term: frontmatter
+  definition: "YAML metadata at the top of a markdown file enclosed in --- delimiters. Used to control document ordering, grouping, and display properties."
+- term: mermaid
+  definition: "A JavaScript diagramming and charting tool that renders markdown-inspired text definitions to create and modify complex diagrams. Supported in kontexta Publish for flowcharts, sequence diagrams, and more."
+- term: SPA
+  definition: "Single Page Application — a web application that loads a single HTML page and dynamically updates content as the user interacts with the app. kontexta Publish generates a self-contained SPA."
+- term: hash routing
+  definition: "A client-side routing technique that uses the URL hash fragment (#) to determine which content to display. Enables deep linking and browser history navigation without server configuration."
+- term: scroll-spy
+  definition: "A UI pattern that automatically highlights the current section in the table of contents as the user scrolls through the page content."
+- term: kxta-core
+  definition: "The core kontexta library that provides vault management, file indexing, git integration, and MCP tool implementations. Used by kontexta Publish to read knowledge files."
+- term: pipeline
+  definition: "The build process that reads markdown files, renders them to HTML, builds navigation and search indexes, and assembles the final single-file HTML output."
+- term: seed docs
+  definition: "Default documentation files bundled with kontexta Publish. Shown when no vault documents are found, providing immediate documentation about the tool itself."
+- term: three-pane layout
+  definition: "The default kontexta Publish layout with three columns: sidebar navigation (left), main content area (center), and table of contents (right)."
+```
+
+## Usage
+
+To add your own glossary terms, use the `glossary` block in any markdown file:
+
+```markdown
+```glossary
+- term: YourTerm
+  definition: Your definition here.
+```
+```
+
+Terms are automatically:
+- Sorted alphabetically
+- Indexed for search
+- Displayed in a clean grid layout

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/seeds.d.ts

@@ -0,0 +1,3 @@
+import type { VaultReader } from "../source/reader.js";
+/** A VaultReader that serves seed docs when no vault is available. */
+export declare function createSeedReader(): VaultReader;

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/seeds.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import matter from "gray-matter";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Read a seed file from src/seeds (dev) or dist/seeds (built). */
+function readSeed(name) {
+    const candidates = [join(__dirname, name), join(__dirname, "../seeds", name)];
+    for (const p of candidates) {
+        try {
+            return readFileSync(p, "utf8");
+        }
+        catch { /* try next */ }
+    }
+    throw new Error(`seed file not found: ${name}`);
+}
+/** Parse a seed markdown file into a VaultDoc. */
+function parseSeed(name) {
+    const raw = readSeed(name);
+    const { data, content } = matter(raw);
+    const slug = name.replace(/^\d+-/, "").replace(/\.md$/, "");
+    return {
+        id: parseInt(name.split("-")[0], 10),
+        path: `/seeds/${name}`,
+        title: data.title || slug,
+        content,
+    };
+}
+/** All seed docs, lazily loaded. */
+let _cache = null;
+function loadSeeds() {
+    if (_cache)
+        return _cache;
+    _cache = [
+        parseSeed("01-overview.md"),
+        parseSeed("02-api.md"),
+        parseSeed("03-improvements.md"),
+        parseSeed("04-glossary.md"),
+    ];
+    return _cache;
+}
+/** A VaultReader that serves seed docs when no vault is available. */
+export function createSeedReader() {
+    const seeds = loadSeeds();
+    const folder = "seeds";
+    return {
+        listFolders: () => [folder],
+        listDocs: (f) => f === folder
+            ? seeds.map(({ id, path, title }) => ({ id, path, title }))
+            : [],
+        read: (id) => seeds.find((d) => d.id === id),
+    };
+}

package/bundle/standalone/node_modules/kxta-publish/dist/source/enumerate.d.ts

@@ -0,0 +1,3 @@
+import type { VaultReader } from "./reader.js";
+import type { DocFile } from "../types.js";
+export declare function enumerateDocs(reader: VaultReader, folders: string[], projectPath?: string): DocFile[];

package/bundle/standalone/node_modules/kxta-publish/dist/source/enumerate.js

@@ -0,0 +1,50 @@
+import matter from "gray-matter";
+import { basename } from "node:path";
+function firstH1(md) {
+    const m = md.match(/^#\s+(.+?)\s*$/m);
+    return m?.[1];
+}
+/** Strip a leading numeric ordering prefix and the .md extension → slug. */
+function slugFromPath(path) {
+    return basename(path).replace(/\.md$/i, "");
+}
+export function enumerateDocs(reader, folders, projectPath) {
+    const out = [];
+    for (const folder of folders) {
+        for (const meta of reader.listDocs(folder, projectPath)) {
+            // Skip unreadable docs (e.g. DB row points at a path that was deleted
+            // out from under the watcher). Without this, a single orphan row
+            // would tank the entire publish run with an ENOENT — the user clicks
+            // "Publish" and gets a 500 with no actionable signal. Log the path
+            // so it shows up in the server logs for cleanup.
+            let raw;
+            try {
+                raw = reader.read(meta.id);
+            }
+            catch (err) {
+                console.warn(`[publish] skipping unreadable doc id=${meta.id} path=${meta.path}: ${err.message}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = matter(raw.content);
+            }
+            catch (err) {
+                console.warn(`[publish] skipping doc with bad frontmatter id=${meta.id} path=${meta.path}: ${err.message}`);
+                continue;
+            }
+            const fm = parsed.data;
+            const body = parsed.content;
+            out.push({
+                id: meta.id,
+                folder,
+                path: raw.path,
+                slug: slugFromPath(raw.path),
+                frontmatter: fm,
+                body,
+                title: fm.title ?? firstH1(body) ?? meta.title,
+            });
+        }
+    }
+    return out;
+}

package/bundle/standalone/node_modules/kxta-publish/dist/source/reader.d.ts

@@ -0,0 +1,20 @@
+/** Metadata for one vault doc (no body). */
+export interface VaultDocMeta {
+    id: number;
+    path: string;
+    title: string;
+}
+/** Full vault doc (with body). */
+export interface VaultDoc extends VaultDocMeta {
+    content: string;
+}
+/** Abstraction over the vault so render logic is testable without a DB. */
+export interface VaultReader {
+    listFolders(projectPath?: string): string[];
+    listDocs(folder: string, projectPath?: string): VaultDocMeta[];
+    read(id: number): VaultDoc;
+}
+/** Real reader backed by kxta-core (in-process; no MCP round-trip). */
+export declare function createCoreReader(opts?: {
+    projectPath?: string;
+}): VaultReader;

package/bundle/standalone/node_modules/kxta-publish/dist/source/reader.js

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import { getDataDir, listFiles, readFile, listProjectFoldersWithFiles } from "kxta-core";
+/** Real reader backed by kxta-core (in-process; no MCP round-trip). */
+export function createCoreReader(opts) {
+    const dataDir = getDataDir();
+    const projectPath = opts?.projectPath;
+    const rootDir = projectPath
+        ? projectPath
+        : join(dataDir, "knowledge");
+    return {
+        listFolders: () => listProjectFoldersWithFiles(rootDir),
+        listDocs: (folder) => listFiles({ dataDir, filters: { folder, project_path: projectPath } })
+            .filter((f) => f.path.endsWith(".md"))
+            .map((f) => ({ id: f.id, path: f.path, title: f.title })),
+        read: (id) => {
+            const r = readFile(id);
+            return { id: r.id, path: r.path, title: r.title, content: r.content };
+        },
+    };
+}