Everything You Ever Wanted to Know About Chidi.md

What It Does

Delivers the full-featured Chidi.md operating experience, including individual file selection, multi-file selection, and recursive folder scanning.

How It Works

Leverages the modern W3C File System Access API (window.showDirectoryPicker()). When the user clicks "Scan Folder", the browser prompts for folder authorization and recursively traverses directory handles to stream every .md file into application memory.

Why It Works

Allows instant ingestion of large personal wikis, Obsidian vaults, and project documentation trees without manual file-by-file picking or compression archives.

What It Does

Provides complete document viewing, markdown parsing, local AI interaction, session saving, and multi-file loading.

How It Works

File loading operates via the standardized HTML5 <input type="file" multiple accept=".md"> element. When showDirectoryPicker is absent, attempting to "Scan Folder" gracefully alerts the user with platform-specific instructions while preserving full multi-file selection via "ADD FILES".

Why It Works

Maintains cross-browser accessibility and deterministic behavior without forcing non-standard polyfills or breaking the no-build philosophy.

What It Does

Caches all 37 distinct DOM element references into a single immutable elements dictionary and manages application lifecycle through an explicit, reactive state store.

How It Works

1. On DOMContentLoaded, elements queries every ID defined in index.html (verified at build time by tests/check_structure.py).
2. state holds loadedFiles, navigation pointers (history, historyIndex), active markdown content, conversation turns (chatHistory), active model configuration (modelSettings), query status (isAsking), and view tracking (viewId).
3. updateUI() inspects state conditions to dynamically enable or disable control buttons (disabling navigation when history bounds are reached, disabling AI features when no files are loaded, locking forms during generation).

Why It Works

Eliminates fragmented DOM lookups across functions. Centralizing state guarantees that UI rendering is a deterministic projection of current memory.

What It Does

Transforms arbitrary Markdown syntax into clean HTML and aggressively neutralizes Cross-Site Scripting (XSS) vectors, malicious iframe injections, and JavaScript URLs before injection into the DOM.

How It Works

1. Input text is passed to convertMarkdownToHtml(markdownText).
2. marked.parse(markdownText) executes client-side AST tokenization and HTML generation via pinned marked@18.0.14.
3. The generated HTML string passes immediately through DOMPurify.sanitize() via pinned DOMPurify@3.4.16, stripping dangerous tags (<script>, <iframe>, <object>) and hostile attributes (onload, onerror, javascript:).
4. The sanitized markup is assigned to markdownDisplay.innerHTML. tests/check_structure.py enforces that no other dynamic innerHTML assignment exists in main.js.

Why It Works

Guarantees zero script execution from untrusted Markdown documents or manipulated model replies. Pinned Subresource Integrity (SRI) hashes ensure CDN scripts cannot be compromised in transit.

What It Does

Bridges Chidi.md to any local Large Language Model server, supporting both Ollama's native REST endpoints and OpenAI-compatible completions APIs with automatic payload normalization.

How It Works

1. URL Verification: isLocalUrl(url) validates that the configured URL targets a loopback interface (localhost, 127.0.0.1, [::1], or *.localhost). Non-local addresses are rejected immediately.
2. Ollama Adapter: Formats requests to {base}/api/chat with {model, messages, stream: false} and extracts response.message.content. Models are queried via GET {base}/api/tags and capability-checked via POST {base}/api/show.
3. OpenAI-Compatible Adapter: Formats requests to {base}/chat/completions with {model, messages} and extracts choices[0].message.content. Compatible with LM Studio, llama.cpp server, LocalAI, and vLLM.

Why It Works

Decouples the user's interface from specific model vendors while ensuring that all inference traffic is air-gapped on the local machine.

What It Does

Prevents race conditions and late model responses from bleeding into newly opened documents when users navigate or restart while an AI query is in flight.

How It Works

1. Each time a file is displayed or a session restarts, state.viewId increments:

   const displayFile = (index) => {
       state.viewId++;
       ...
   };

2. When an AI request starts, startRequest() captures the current capturedViewId = state.viewId along with a unique request ID.
3. Upon response resolution, isStale(reqId, capturedViewId) checks if state.viewId !== capturedViewId.
4. If the view has drifted, the response text is dropped, the activity spinner hides, and the status bar alerts: "Late reply from <model> dropped (file changed)."

Why It Works

Local LLMs can take seconds or minutes to generate responses. View invariance ensures that answers never contaminate the wrong document, preserving conversation integrity.

What It Does

Persists the entire active workspace (loaded files, view history stack, chat conversation turns, and model settings) to browser localStorage under chidiMdSession, complete with quota protection.

How It Works

1. Serialization: saveSession() compiles {loadedFiles, history, historyIndex, chatHistory, modelSettings} into a JSON string and commits it to localStorage.setItem(SESSION_STORAGE_KEY, ...).
2. Quota Circuit Breaker: If the write throws a storage quota error (typically ~5 MB in modern browsers), the catch block measures payload size and reports: "Error: Session is ~X MB; browser storage is full. Your previous save is still kept."
3. Hydration & Quarantine: restoreSession() parses saved data, restores state pointers, and automatically purges any legacy apiKey or Gemini data from earlier revisions.

Why It Works

Users can refresh their browser, close tabs, or return days later without losing their place or loaded files, with graceful degradation when quotas are exceeded.

What It Does

Generates a concise, structured executive summary of the currently viewed Markdown document, highlighting core arguments, conclusions, and key takeaways.

How It Works

Constructs a single-turn prompt containing the document content and the directive: "Provide a concise summary of the following document. Highlight key points and main ideas." The reply is parsed through DOMPurify and appended to the display with an AI heading badge.

Why It Works

Enables instant scanning of lengthy technical documents or research notes without reading several thousand words manually.

What It Does

Analyzes the current document and synthesizes 3 to 5 insightful, probing questions that a reader might ask, rendering them as interactive, clickable buttons in the console.

How It Works

1. Directs the model: "Based on the following document, suggest 3-5 insightful questions a reader might ask to better understand or explore the content."
2. Parses numbered list items from the response text into distinct question strings.
3. Renders each question as an interactive button (.suggested-question-btn). Clicking any button populates the query and automatically triggers the follow-up pipeline.

Why It Works

Sparks intellectual curiosity and helps readers discover blind spots or implicit assumptions in complex documentation.

What It Does

Provides a persistent "Ask about this file..." input bar below the document, maintaining a multi-turn conversation thread scoped exclusively to the active file.

How It Works

1. Submitting a question pushes {role: "user", content: question} to state.chatHistory.
2. The conversation history is dispatched to the local model server. During inference, the input box, Ask button, and all AI controls are disabled.
3. The model's reply is added to state.chatHistory as {role: "assistant", content: reply} and appended to the rendered output. Focus returns to the input box.

Why It Works

Provides a true conversational copilot experience where users can ask progressive questions, clarify specific clauses, and drill into document specifics.

What It Does

Executes a single, comprehensive inquiry across every Markdown file loaded in the workspace, synthesizing facts from dozens or hundreds of files into one coherent answer.

How It Works

1. Clicking "Ask All" opens the asynchronous Input Modal prompting for the question.
2. Concatenates all loaded files into a single context block:

   File: notes/arch.md
   ---
   [Content]
   ===
   File: notes/decisions.md
   ---
   [Content]

3. Directs the model to answer the query specifically citing evidence across the provided files. The synthesized result is appended to the active screen.

Why It Works

Eliminates the friction of manually searching across fragmented notes. Users can ask "Where did we decide our caching strategy?" and receive a cited synthesis instantly.

What It Does

Queries the local model server to list available models, dynamically detects their capabilities, and disables embedding-only models that cannot participate in conversational chat.

How It Works

1. On Ollama, queries GET /api/tags for model names, then calls POST /api/show for each model to inspect capabilities. If capabilities lacks completion, chat is flagged false.
2. On OpenAI-compatible servers, models with embed in their ID are flagged false.
3. fillModelSelect() sorts capable models first and appends disabled options for embedding models, preventing accidental selection.

Why It Works

Prevents confusing runtime errors caused by querying embedding models (such as nomic-embed-text) for conversational text generation.

What It Does

Styles Chidi.md as a vintage CRT terminal workstation with custom monospaced typography, amber/cyan accent highlights, and subtle terminal borders.

How It Works

Loads Google Fonts (Space Mono for legible body reading, VT323 for CRT console titles). Uses a dark palette (#0d1117 background, #38bdf8 cyan borders) and fluid CSS grid/flexbox layouts that adapt seamlessly to various desktop viewport sizes.

Why It Works

Fosters a focused, distraction-free reading mindset reminiscent of early Unix workstations without sacrificing modern layout reliability.

What It Does

Maintains an explicit navigation history stack of loaded files, driving the PREV and NEXT buttons with boundary detection and duplicate skipping.

How It Works

1. state.history stores an ordered array of file indexes representing viewed documents. state.historyIndex tracks the current cursor position.
2. Clicking PREV decrements historyIndex; clicking NEXT increments it.
3. updateUI() disables PREV when at index 0 and disables NEXT when at the end of the history stack.

Why It Works

Provides predictable, browser-like forward/backward navigation across documents without losing state or reloading content.

What It Does

Powers interactive dialog overlays (Input Modal, Model Settings, Restore Confirmation) using standard JavaScript Promises rather than blocking prompt() or confirm() calls.

How It Works

showInputModal(config) returns a Promise. It unhides the modal, sets custom labels and placeholders, and binds Enter/Escape keyboard listeners. Confirming resolves with the string value; cancelling or pressing Escape resolves with null. The cleanup closure removes all listeners upon resolution.

Why It Works

Native browser prompts (window.prompt) freeze the execution thread and clash visually with custom themes. The Promise modal pattern allows clean await syntax while preserving theme consistency.

What It Does

Provides real-time feedback via the footer status readout (loaded file count, system logs, error alerts) and a header activity loader spinner.

How It Works

1. fileCountDisplay.textContent reflects state.loadedFiles.length.
2. messageBox.textContent renders standardized log prefixes (SYSTEM LOG: Standby., SYSTEM LOG: Error: ...).
3. loader.classList.remove('hidden') activates an animated CSS spinner in the header during asynchronous I/O or model inference.

Why It Works

Operators always have immediate visibility into application state, knowing precisely when operations are queued, active, or errored.

What It Does

Defines the trust boundary between user files, external model outputs, and DOM execution contexts.

How It Works

Both user-provided Markdown files and model responses are treated as hostile, untrusted data. Even if a Markdown file contains embedded <script>alert(1)</script>, <img src=x onerror=...>, or [click](javascript:...), it is filtered through DOMPurify before reaching the DOM.

Why It Works

Users frequently download Markdown files or repositories from the public internet. Defense-in-depth sanitization guarantees that opening a hostile Markdown file can never compromise the user's browser.

What It Does

Enforces that outbound network requests initiated by Chidi.md can only target local loopback network adapters on the user's machine.

How It Works

isLocalUrl(value) parses the input via the browser's URL API and confirms:

• The protocol is http: or https:.
• The hostname is strictly localhost, 127.0.0.1, [::1], or ends with .localhost.

Any remote domain (e.g. api.openai.com or evil-server.com) is rejected immediately with an error.

Why It Works

Eliminates SSRF vectors and ensures that sensitive document contents are never accidentally transmitted across the public internet.

What It Does

Ensures that structural headings and content elements are assembled with DOM-safe APIs rather than raw template strings.

How It Works

When appending model output, appendAiOutput() builds container elements, sets headings via heading.textContent = titleText, and processes body markdown through convertMarkdownToHtml(). Template strings are never directly assigned to innerHTML.

Why It Works

Prevents title or prompt injection attacks from escaping HTML boundaries, maintaining structural integrity across all dynamic content.

What It Does

Scans incoming session payloads for legacy credentials (e.g. older versions that stored Gemini API keys) and permanently purges them upon hydration.

How It Works

When restoring from localStorage, restoreSession() checks for parsedData.apiKey or parsedData.geminiChatHistory. If detected, it immediately deletes those keys and saves the sanitized session back to disk.

Why It Works

Eliminates orphaned API secrets from user storage, ensuring adherence to the Zero-Key Mandate.

What It Does

A fast, zero-dependency Python script that validates the structural agreement between index.html and main.js in under 100 milliseconds.

How It Works

1. Verifies that every ID queried via document.getElementById() in main.js exists exactly once in index.html.
2. Verifies that no duplicate IDs exist in index.html.
3. Verifies that all local script and stylesheet paths exist on disk.
4. Enforces that every innerHTML assignment in main.js is either a string literal or passes through convertMarkdownToHtml().
5. Verifies that all CDN scripts include exact version numbers and valid SRI sha384 hashes.

Why It Works

Catches wiring bugs, typos, and security regressions before code ever reaches a browser or version control.

What It Does

An automated auditor that checks documentation files for link drift, stale roadmap items, invalid decision references, and unfulfilled template placeholders.

How It Works

1. Scans all project documentation in docs/ and the repository root.
2. Validates that every Markdown link targets an existing file on disk.
3. Verifies that referenced Roadmap IDs (e.g. P1-01) and Decision IDs (e.g. D-007) exist in their canonical files.
4. Audits docs/HANDOFF.md session logs for proper formatting and limits.

Why It Works

Guarantees that documentation remains an accurate, living reflection of codebase reality rather than decaying over time.

What It Does

An offline end-to-end test suite running 34 automated browser tests across both Chromium and Firefox, simulating live user workflows and verifying network boundaries.

How It Works

1. Uses Playwright to spin up headless browser instances against an offline mock server. Pinned CDN libraries are served directly from node_modules.
2. Tests file loading, duplicate skipping, and history navigation.
3. Tests hostile Markdown sanitization (verifying that onerror payloads are stripped).
4. Tests local URL validation (verifying that non-local URLs are refused).
5. Tests live Ollama and OpenAI-compatible API mocking, model capability filtering, and late answer quarantine (P2-05).
6. Tests storage quota exhaustion handling (P2-02).

Why It Works

Proves that the entire application operates seamlessly across major desktop rendering engines without relying on external network connectivity during CI runs.

What It Does

Runs the fast structural checks and dual-browser Playwright smoke test on every push and pull request.

How It Works

Executes on GitHub Actions Ubuntu runners with pinned Node and Python environments. Actions are pinned to immutable commit SHAs for supply-chain security.

Why It Works

Enforces that no breaking change or security regression can be merged into main without passing automated verification.