ai

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## What this is
+
+**TIL ("Today I Learned")** — David Windham's personal knowledge base and notes
+site, published at https://davidawindham.com/til/ (baseUrl `/til/`). It's a place
+to store notes, documentation, lists, and posts. Built with
+[Docusaurus](https://docusaurus.io/) v3.10.x (React 18). Content is Markdown/MDX,
+authored partly through Obsidian (each content dir may have a git-ignored
+`.obsidian/` vault).
+
+Remotes: `origin` → GitHub (windhamdavid/til), `code` → self-hosted Gitea
+(code.davidawindham.com/david/til). `editUrl`s point at the Gitea `main` branch.
+
+## Commands
+
+```bash
+npm start          # dev server with hot reload (docusaurus start)
+npm run build      # static production build → ./build
+npm run serve      # serve the built site locally
+npm run clear      # clear the .docusaurus cache
+npm run deploy     # docusaurus deploy
+```
+
+There is no test suite or linter. The build is the check: `npm run build` must
+pass. Broken Markdown links and images **throw** (see `markdown.hooks` in the
+config), so a typo in a relative link or image path will fail the build.
+
+## Layout
+
+Content is split into several Docusaurus instances, each its own top-level dir
+with its own sidebar file:
+
+| Dir       | Route        | Sidebar               | Type  |
+|-----------|--------------|-----------------------|-------|
+| `docs/`   | `/docs/`     | `sidebars.js`         | docs (classic preset) |
+| `notes/`  | `/notes/`    | `sidebarsnotes.js`    | docs  |
+| `lists/`  | `/lists/`    | `sidebarslists.js`    | docs  |
+| `posts/`  | `/posts/`    | auto                  | blog  |
+| `ideas/`  | `/ideas/`    | auto                  | blog (path may not exist yet) |
+
+- `src/pages/` — standalone pages (`about.md`, `help.md`, `ai.mdx`, `map.md`, `index.md`).
+- `src/theme/` — swizzled theme components (custom `SearchBar`, `BlogLayout`, `BlogListPage`).
+- `src/components/` — e.g. `ABCNotation.jsx` (music notation; `abcjs`/`react-piano` are deps).
+- `src/css/custom.css` — global styles.
+- `static/` — assets (`img/`, `pdf/`, `katex/`). **Git-ignored** (`/static`).
+- `build/`, `.docusaurus/`, `node_modules/` — generated/installed; never edit.
+
+Config lives in `docusaurus.config.js`. When adding a new docs/blog instance,
+register the plugin there and add a matching sidebar file.
+
+## Content conventions
+
+- Posts use a `YYYY/YYYY-MM-DD-posts.md` naming pattern with front matter
+  (`title`, `slug`, `description`, `tags`, `image`, often
+  `hide_table_of_contents: true`). Use `<!-- truncate -->` to mark the fold.
+- Dark mode is the default; Mermaid diagrams are enabled.
+- Search is `docusaurus-lunr-search` (local), not Algolia.
+- `src/pages/ai.mdx` is **git-ignored** — don't assume it's committed.
+- The README holds a human-readable changelog/LOG of upgrades and changes.
+
+## Working here
+
+- This is a personal site — keep the author's voice in prose content; don't
+  rewrite or "improve" existing notes/posts unless asked.
+- When editing content, verify relative links and image paths so the build
+  doesn't throw.
+- Commit/push only when asked. The default working branch is `main`.
+
+## Planned: AI assistant (replacing Markprompt)
+
+[ai.mdx](src/pages/ai.mdx) currently uses the third-party **Markprompt** widget (their hosted
+vector DB + OpenAI). It's being replaced with a self-hosted, Claude-powered RAG assistant that
+answers **only** from this site's content and **links back to the source pages** via Anthropic
+native citations. Full plan: `~/.claude/plans/radiant-wiggling-sunrise.md`.
+
+**The backend is NOT in this repo** — it's an extension of `/Users/david/Sites/ralph/mcp-server`
+(`better-sqlite3` + `sqlite-vec`, local Ollama embeddings, Hono server on `:3001`). See that
+repo's `CLAUDE.md` for the backend build. This repo owns only the **frontend wiring**:
+
+- **Indexing (runs from ralph, reads this repo):** `ralph/mcp-server/scripts/ingest-daw-til.mjs`
+  walks `docs/ notes/ lists/ posts/`, **skips `draft|unlisted|private` frontmatter and `_`-prefixed
+  partials**, and stores each chunk's public TIL URL + title so citations resolve. URL mapping must
+  mirror [docusaurus.config.js](docusaurus.config.js): docs/notes/lists → `/til/<route>/<path>`
+  (respecting `slug:/` and `index.md`→dir root); **posts → `/til/posts/<slug>` (slug, not filename)**.
+  Re-run after every content change.
+- **Widget, site-wide:** add `clientModules: ['./src/clientModules/ask-widget.js']` to
+  docusaurus.config.js — a net-new module that injects the `<script src=".../ask/widget.js"
+  data-api-url=".../ask/api/ask">` tag (the widget bundle is served by the ralph backend).
+- **Replace `<Markprompt>` in ai.mdx** with the widget's inline mode (`<div id="dawask-inline">`);
+  update the page copy (Claude + working citation links now). The new page has **no secret** (key is
+  server-side), so **remove `/src/pages/ai.mdx` from [.gitignore](.gitignore)** and commit it.
+- **Drop the dep:** remove the `markprompt` import and the `markprompt` entry in
+  [package.json](package.json); `npm install`; `grep -r markprompt src/` to confirm it's gone.
+
+Model: Claude **Haiku 4.5** (cheap, public endpoint). Generation/citations/CORS/rate-limiting all
+live in the ralph backend.

README.md

@@ -3,8 +3,25 @@
 
 ---  
 
-## Notes:
+## About
+This is a place to store some notes and documentation. It was originally built as a way to make notes on interesting things I learn based on one of my favorite sub-reddit/[TIL](https://www.reddit.com/r/todayilearned/). While installing it the first time I wrote 'Today I learned that Google will translate to and from [Zulu](https://en.wikipedia.org/wiki/Zulu_language)'.  
+
+![zulu](https://davidawindham.com/til/img/zulu.png)  
+
+ > The page above in this site referring to the database and computer [operating system](https://en.wikipedia.org/wiki/Ubuntu) and not the [Zulu philosophy](https://en.wikipedia.org/wiki/Ubuntu_(philosophy))  of a universal bond of sharing that connects all humanity. 
+
+I'm often searching online documentation for answers to commands, configurations, and error messages. I figured that since I spend most of my working time with the terminal, git, and text files, a more efficient and easier method of documenting the time I spend reading other documentation would be to build my own TIL. This way the information I learn will be easy to record, search and edit. The problem is that I've found myself repeating those searches because of the breadth and depth of the amount of functions and libraries involved in development. My wife suggested I call it TIHIDI 'this is how I did it' after explaining what I was working on. It makes sense to use a static documentation instead of database because it's quicker, easier to search, under version control, and the file formats are interoperable with other software and publishing frameworks.  
 
+I'm hoping it'll help me keep my bookmarks as little less cluttered and it'll leave my [desk page](https://davidawindham.com/desk) free for longer form essays. I'll keep the LOG in the [README](https://code.davidawindham.com/david/til/src/master/README.md), add a [help page](/help), and some [vi cheat sheets](/docs/shell/vi) to get started because I'm always forgetting some of them.
+
+Here's a map 👇🏼
+
+[![md-graph map](https://davidawindham.com/til/img/til.jpg)](https://davidawindham.com/til/img/til.jpg)
+
+## Log
+
+- 26/06/06 - reworking the [AI page](https://davidawindham.com/til/ai): dropping Markprompt/OpenAI for a self-hosted assistant — Claude (Haiku) + local vector search over my own notes/docs/lists/posts, answers that link back to the source pages, as a little pop-up "Clippy" widget I can drop on any of my sites. Only answers from my stuff. Backend rides on my [ralph](https://code.davidawindham.com/david/ralph) RAG/MCP server (SQLite + sqlite-vec + local Ollama embeddings).
+- 26/06/06 - upgrades ( 3.9.2 👉🏼 3.10.1) all good 👍🏼
 - 24/11/23 - dev branch for .devcontainer / codespace
 - 24/11/17 - upgrades ( 3.5.2 👉🏼 3.6.1 ) all good 👍🏼
   - 3.6 switched to Rust 🦀 rspack, SWC, Lightning CSS for faster builds
@@ -29,19 +46,3 @@ Migrated this version from Gitbook because it wasn't playing nicely with Node.js
 
 While working on another project yesterday afternoon, I ran into set of documentation ([https://docs.feathersjs.com/](https://docs.feathersjs.com/)) that I spent a lot of time reading and will likely forget about sometime soon after I abandon using the library in other projects. Of course I stuffed a bookmark of the documentation into my quasi organized set of chrome bookmarks based on each project, but the fact that the documentation was hosted using [Gitbook](https://github.com/GitbookIO/gitbook), reminded me of a practice I've seen others do.
 
-## About
-This is a place to store some notes and documentation. It was originally built as a way to make notes on interesting things I learn based on one of my favorite sub-reddit/[TIL](https://www.reddit.com/r/todayilearned/). While installing it the first time I wrote 'Today I learned that Google will translate to and from [Zulu](https://en.wikipedia.org/wiki/Zulu_language)'.  
-
-![zulu](https://davidawindham.com/til/img/zulu.png)  
-
- > The page above in this site referring to the database and computer [operating system](https://en.wikipedia.org/wiki/Ubuntu) and not the [Zulu philosophy](https://en.wikipedia.org/wiki/Ubuntu_(philosophy))  of a universal bond of sharing that connects all humanity. 
-
-
-
-I'm often searching online documentation for answers to commands, configurations, and error messages. I figured that since I spend most of my working time with the terminal, git, and text files, a more efficient and easier method of documenting the time I spend reading other documentation would be to build my own TIL. This way the information I learn will be easy to record, search and edit. The problem is that I've found myself repeating those searches because of the breadth and depth of the amount of functions and libraries involved in development. My wife suggested I call it TIHIDI 'this is how I did it' after explaining what I was working on. It makes sense to use a static documentation instead of database because it's quicker, easier to search, under version control, and the file formats are interoperable with other software and publishing frameworks.  
-
-I'm hoping it'll help me keep my bookmarks as little less cluttered and it'll leave my [desk page](https://davidawindham.com/desk) free for longer form essays. I'll keep the LOG in the [README](https://code.davidawindham.com/david/til/src/master/README.md), add a [help page](/help), and some [vi cheat sheets](/docs/shell/vi) to get started because I'm always forgetting some of them.
-
-Here's a map 👇🏼
-
-[![md-graph map](https://davidawindham.com/til/img/til.jpg)](https://davidawindham.com/til/img/til.jpg)