From 35db5d2aed917f9fcf04a55f15a8436bfe97d47c Mon Sep 17 00:00:00 2001
From: edoch <edo_chio@hotmail.it>
Date: Tue, 17 Mar 2026 00:09:56 +0100
Subject: [PATCH] docs: add TODO-0114 (mdbook-cmdrun) and TODO-0115 (asciinema)

---
 docs/spec/todos/TODO-0114.md | 52 ++++++++++++++++++++++++++++++
 docs/spec/todos/TODO-0115.md | 61 ++++++++++++++++++++++++++++++++++++
 docs/spec/todos/index.md     |  2 ++
 3 files changed, 115 insertions(+)
 create mode 100644 docs/spec/todos/TODO-0114.md
 create mode 100644 docs/spec/todos/TODO-0115.md

diff --git a/docs/spec/todos/TODO-0114.md b/docs/spec/todos/TODO-0114.md
new file mode 100644
index 0000000..d841288
--- /dev/null
+++ b/docs/spec/todos/TODO-0114.md
@@ -0,0 +1,52 @@
+---
+id: 114
+title: "Auto-generate CLI output examples in mdBook with mdbook-cmdrun"
+status: todo
+priority: medium
+created: 2026-03-17
+depends_on: []
+blocks: []
+---
+
+# TODO-0114: Auto-generate CLI output examples in mdBook with mdbook-cmdrun
+
+## Summary
+
+Use `mdbook-cmdrun` to auto-generate CLI output examples in the book by running `mdvs` commands against `example_kb/` at build time. This keeps book examples always in sync with actual tool output.
+
+## Details
+
+### Setup
+
+- Add `mdbook-cmdrun` as a preprocessor in `book.toml`
+- Install `mdbook-cmdrun` in the GitHub Pages deploy workflow (TODO-0095)
+
+### Usage
+
+Replace hand-written output blocks in book pages with `cmdrun` directives:
+
+```markdown
+<!-- cmdrun mdvs search "rust" example_kb --output text -->
+```
+
+During `mdbook build`, the preprocessor runs the command and injects stdout into the page.
+
+### Scope
+
+- Identify all book pages with CLI output examples
+- Replace static output with `cmdrun` directives where feasible
+- Some examples may need to stay static (e.g., error examples, hypothetical output for features not yet implemented)
+
+### Considerations
+
+- `example_kb/` must be accessible from the book build directory — may need to adjust the working directory or use relative paths
+- Build time increases since commands run during `mdbook build`
+- CI workflow needs `mdvs` binary available (build it before `mdbook build`)
+- Commands that require a built index (search, info) need a prior `mdvs build` step in CI
+- Consider a `scripts/book-setup.sh` that runs `mdvs init` + `mdvs build` on `example_kb/` before `mdbook build`
+
+### Files
+
+- `book.toml` — add `mdbook-cmdrun` preprocessor config
+- `book/src/commands/*.md` — replace static output with `cmdrun` directives
+- `.github/workflows/deploy-book.yml` — install `mdbook-cmdrun`, build `mdvs`, run setup before `mdbook build`
diff --git a/docs/spec/todos/TODO-0115.md b/docs/spec/todos/TODO-0115.md
new file mode 100644
index 0000000..b0d4683
--- /dev/null
+++ b/docs/spec/todos/TODO-0115.md
@@ -0,0 +1,61 @@
+---
+id: 115
+title: "Embed asciinema recordings in mdBook for interactive demos"
+status: todo
+priority: medium
+created: 2026-03-17
+depends_on: []
+blocks: []
+---
+
+# TODO-0115: Embed asciinema recordings in mdBook for interactive demos
+
+## Summary
+
+Record terminal sessions with asciinema and embed them in mdBook pages. Gives readers a feel for the CLI workflow without requiring a live backend.
+
+## Details
+
+### Recording
+
+- Use `asciinema rec` to record key workflows (init, search, build, check)
+- Store `.cast` files in `book/assets/casts/` (or similar)
+- Keep recordings short and focused — one per workflow, not one mega-session
+
+### Embedding
+
+- Use the asciinema player (JavaScript widget) to embed recordings in book pages
+- Add the player JS/CSS via `output.html.additional-js` and `output.html.additional-css` in `book.toml`
+- Embed with HTML in markdown:
+
+```html
+<div id="demo-search"></div>
+<script>
+  AsciinemaPlayer.create('/assets/casts/search.cast', document.getElementById('demo-search'), {
+    cols: 100,
+    rows: 24,
+    theme: 'monokai'
+  });
+</script>
+```
+
+### Suggested recordings
+
+- **Getting started**: `mdvs init` → `mdvs search` (instant search workflow)
+- **Validation**: `mdvs init` → `mdvs check` (validation-only workflow)
+- **Customized build**: `mdvs init` → `mdvs build --set-model ...` → `mdvs search`
+- **Incremental build**: edit a file → `mdvs build` (shows only changed files re-embedded)
+
+### Considerations
+
+- Recordings need to be re-recorded when output format changes significantly
+- Player assets can be loaded from CDN or vendored locally
+- `.cast` files are small (text-based JSON) — fine to commit to repo
+- Consider adding a `scripts/record-demos.sh` helper for reproducible recordings against `example_kb/`
+
+### Files
+
+- `book.toml` — add asciinema player JS/CSS
+- `book/assets/casts/*.cast` — recorded sessions
+- `book/src/getting-started.md` — embed intro recording
+- `book/src/commands/*.md` — embed per-command recordings (optional)
diff --git a/docs/spec/todos/index.md b/docs/spec/todos/index.md
index 1a57ef8..61ae58b 100644
--- a/docs/spec/todos/index.md
+++ b/docs/spec/todos/index.md
@@ -115,3 +115,5 @@
 | [0111](TODO-0111.md) | Reject unknown fields in mdvs.toml with deny_unknown_fields | done | high | 2026-03-14 |
 | [0112](TODO-0112.md) | Document JSON output format in the mdBook | todo | medium | 2026-03-15 |
 | [0113](TODO-0113.md) | Progress bar for model download and embedding | todo | medium | 2026-03-16 |
+| [0114](TODO-0114.md) | Auto-generate CLI output examples in mdBook with mdbook-cmdrun | todo | medium | 2026-03-17 |
+| [0115](TODO-0115.md) | Embed asciinema recordings in mdBook for interactive demos | todo | medium | 2026-03-17 |