@bojackduy/opencode-learn 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — 2026-08-31
+
+* Initial port of `amosblomqvist/learn` (`pi` extensions: `quiz`, `md-log`, `visual-tools` + `teach`/`visualize` skills + `researcher`/`mermaid-maker`/`svg-maker` agents) to OpenCode `learn` + `learn-tui` plugins.
+* `quiz`/`quiz_batch` — graded, shuffled, `I don't know` + `note`, durable `pendingDir` `.opencode/learn-pending`, 4-state `hit/miss/false-alarm/correct-rejection` solid `bg` inverted.
+* `md_log`/`md_unlog` — `> [!quote] YOU` / `> [!abstract] OPENCODE` + `> [!question|success|failure]` callouts, LaTeX, backfill `client.session.messages`, `chat.message`/`experimental.text.complete`/`tool.execute`.
+* `write_mermaid`/`edit`/`render` + `write_svg`/`edit`/`render` — `opencode-visual-tools` staging, `viz/` publish, `Chrome`/`mmdc` / `rsvg-convert`→`magick`.
+* Installer `npx @bojackduy/opencode-learn` — idempotent `opencode.jsonc`/`tui.json` `plugin` array, `agents/`, `skills/`, `commands/` copy, `OPENCODE_CONFIG_DIR` override, `--uninstall`.
+* Honours original authors: Mario Zechner (`pi`) + Amos Blomqvist (`learn`, video).

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Duy Trinh — Port of amosblomqvist/learn and Mario Zechner's pi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Original pi: Copyright (c) Mario Zechner — https://github.com/mariozechner/pi
+Original learn: Copyright (c) Amos Blomqvist — https://github.com/amosblomqvist/learn
+Video: How I Use AI to Learn Things — https://www.youtube.com/watch?v=kzcI5F4tGiU

package/README.md

@@ -0,0 +1,151 @@
+# opencode-learn
+
+**Pi `learn` system for OpenCode — teaching that locks in, not just delivers.**
+
+> Port of the [`pi` learn harness](https://github.com/amosblomqvist/learn) to [OpenCode](https://opencode.ai). Original system by [**Amos Blomqvist**](https://github.com/amosblomqvist) from [**How I Use AI to Learn Things**](https://www.youtube.com/watch?v=kzcI5F4tGiU) (thumbnail: `pi` by [**Mario Zechner**](https://github.com/mariozechner/pi) / [`earendil-works/pi`](https://github.com/earendil-works/pi)).
+
+[![opencode plugin](https://img.shields.io/badge/opencode-plugin-9cf?style=flat-square)](https://opencode.ai)
+[![TUI](https://img.shields.io/badge/TUI-OpenTUI-purple?style=flat-square)](https://github.com/anomalyco/opentui)
+[![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
+
+## Why
+
+Two brains can hold the same facts — one as disconnected lone facts, the other as a dependency graph where every fact is derivable from a few core truths. Teaching here builds that graph: **nodes** (unconditional truths) → **edges** (motivated discovery, 3Blue1Brown-style `how could I have discovered this?`).
+
+* **Probe → Plan → Teach** — every session locates your edge (graded `quiz` probes), scopes goal (native `question`), plans DAG, then teaches node-by-node with `quiz`-check.
+* **Verifies, not hallucinates** — `researcher` subagent (`task` `subagent_type=researcher`) before any shaky claim.
+* **Logs to Obsidian** — `md_log` mirrors `YOU`/`OPENCODE`/`Quiz`/`Question` as `> [!quote]`/`> [!abstract]`/`> [!question|success|failure]` callouts, LaTeX `$…$` rendered in Obsidian. `viz/` PNGs embed as `![[viz-*.png|500]]`.
+
+Keywords: `opencode` `opencode-plugin` `learn` `teach` `quiz` `md-log` `obsidian` `3blue1brown` `socratic`
+
+## What's inside
+
+| Pi original `amosblomqvist/learn` | Opencode port `personal/.opencode` | Notes |
+|---|---|---|
+| `skills/teach/SKILL.md` | `skills/teach/SKILL.md` | `quiz` + native `question` (custom `ask` removed to cut hallucination, `question` is single source), `task researcher` |
+| `skills/visualize/SKILL.md` | `skills/visualize/SKILL.md` | `task subagent_type=mermaid-maker/svg-maker` + `![[filename|500]]` |
+| `extensions/quiz` | `plugins/learn.ts:quiz` + `quiz_batch` | Graded `single|multi` + `I don't know` + `note`, shuffled, `correctAnswer` by value, TUI durable `pendingDir` `opencode-visual-tools` |
+| `extensions/ask-user-question` | **removed** — use native `question` | One less tool → less overhead/hallucination |
+| `extensions/md-log` | `plugins/learn.ts:md_log/md_unlog` `opencode.json:md_log` | `> [!quote] YOU` / `> [!abstract] OPENCODE` + backfill `client.session.messages` + `chat.message`/`experimental.text.complete`/`tool.execute` |
+| `extensions/visual-tools` `mermaid/svg` | `plugins/learn.ts:write_mermaid/edit/render` + `write_svg/edit/render` | `STAGING_ROOT=tmp/opencode-visual-tools`, `Chrome`+`mmdc` / `rsvg-convert`→`magick`, `viz/` publish |
+| `agents/researcher` `mermaid-maker` `svg-maker` | `agents/{researcher,mermaid-maker,svg-maker}.md` | `researcher` `safe_bash` → `bash:ask` in opencode; makers get `write_*`/`render_*` at **primary** (`* :allow`) per user choice |
+
+Plus `plugins/learn-tui.tsx` — modal TUI `QuizDialog`/`QuizBatchDialog` (4-state `hit/miss/false-alarm/correct-rejection` `success/error/warning` solid `bg` inverted, `0a/15` lighter, `○/✓/✗`), durable `pendingDir` `.opencode/learn-pending` `watch+poll 700ms` + `hb 2s` `.tui-alive`.
+
+## Honour & reference
+
+* **Pi** — [Mario Zechner — `pi` coding agent](https://github.com/mariozechner/pi) / [`earendil-works/pi`](https://github.com/earendil-works/pi) — the runtime this port targets away from.
+* **Learn system** — [Amos Blomqvist — `amosblomqvist/learn`](https://github.com/amosblomqvist/learn) — the teaching philosophy (unconditional truths, `how could I have discovered this?`) and the `quiz`/`ask`/`md-log`/`visual-tools` harness. This port keeps the `probe→plan→teach` DAG and `researcher` verification verbatim.
+* **Video** — [How I Use AI to Learn Things](https://www.youtube.com/watch?v=kzcI5F4tGiU) (`assets/thumbnail.png` in original) — watch first.
+
+> This is a personal port, shared as-is. Original `learn` is for one learner (Amos) — edit `skills/teach/SKILL.md` to fit you.
+
+## Install
+
+### Plugin — simple (no installer)
+
+Add to **both** configs (opencode needs server + TUI):
+
+**`~/.config/opencode/opencode.jsonc`** — server (`learn` + visual):
+```jsonc
+{ "plugin": ["@bojackduy/opencode-learn"] }
+```
+**`~/.config/opencode/tui.json`** — TUI (`learn-tui`):
+```jsonc
+{ "plugin": ["@bojackduy/opencode-learn/tui"] }
+```
+Restart OpenCode. Verify `/md_log`, `quiz`, `write_mermaid` appear in tool list.
+
+Local checkout:
+```jsonc
+// opencode.jsonc
+{ "plugin": ["./path/to/personal/.opencode"] }
+// tui.json
+{ "plugin": ["./path/to/personal/.opencode/plugins/learn-tui.tsx"] }
+```
+
+### Installer — skills + agents + plugins in one command
+
+```bash
+npx -y @bojackduy/opencode-learn@latest
+```
+
+Installs:
+* `plugin` → `opencode.jsonc`/`tui.json` (package spec `@bojackduy/opencode-learn@<version>`)
+* `agents/` → `~/.config/opencode/agents/{researcher,mermaid-maker,svg-maker}.md`
+* `skills/` → `~/.config/opencode/skills/{teach,visualize}/SKILL.md` + `marker-pdf-parser`/`notebooklm-lecture-notes`
+* `commands/` → `~/.config/opencode/commands/{md_log,md_unlog}.md` (if present)
+
+Re-run to update. Then **restart OpenCode**.
+
+Uninstall:
+```bash
+npx -y @bojackduy/opencode-learn@latest --uninstall
+```
+Or global:
+```bash
+npm i -g @bojackduy/opencode-learn@latest
+opencode-learn            # install
+opencode-learn --uninstall # remove
+```
+
+### Manual
+
+Copy `plugins/`, `agents/`, `skills/teach`, `skills/visualize` into `~/.config/opencode/` and add `plugin` entries above.
+
+## Usage
+
+**Mirror to Obsidian**
+```
+/md_log /path/to/note.md   # file must exist — backfills history, mirrors YOU/OPENCODE/Quiz as callouts, LaTeX $…$
+/md_unlog
+```
+View in Obsidian — `viz/` PNGs embed as `![[viz-*.png|500]]`, mermaid `$$…$$`.
+
+**Quiz — probe & check**
+```
+quiz(question="What is 2+2?", options=[{label:"3"}, {label:"4"}], correctAnswer="4", explanation="…")
+quiz_batch(quizzes=[{question:"…", options:[…], correctAnswer:["Red","Blue"], explanation:"…", multiSelect:true}])
+```
+Single → TUI popup `QuizDialog` (single/multi + `I don't know` + note). Batch → deck `1/3→3/3` `QuizBatchDialog` (same 4-state `hit/miss/false-alarm/correct-rejection` solid `bg` inverted). Both durable `pendingDir` `.opencode/learn-pending` — kill `opencode` mid-popup → re-show on restart.
+
+Open forks: native `question` (single/multi `Other`).
+
+**Visual — one correct picture**
+```
+task(subagent_type="mermaid-maker", prompt="graph TD: packet → ordering → reliable stream, 3 nodes only")
+# → returns filename: viz-packet-*.png → embed ![[viz-*.png|500]] (md_log mirrors)
+```
+
+## Publishing (template from `@bojackduy/opencode-loopd`)
+
+This harness follows `opencode-loopd`'s npm + installer template (`~/Code/opencode-loopd`):
+
+* `package.json` — `name:@bojackduy/opencode-learn` `version` `bin:opencode-learn=scripts/install-node.mjs` `files:[plugins,agents,skills,commands,dist]` `publishConfig access public` `peerDependencies @opencode-ai/plugin`
+* `scripts/install-node.mjs` — idempotent `opencode.jsonc`/`tui.json` `plugin` array rewrite (keeps comments, `formatPluginArray`), `OPENCODE_CONFIG_DIR` override, `commands/*.md` + `skills/*` copy, `--uninstall` purge, `ensureDependency` `@opencode-ai/plugin`.
+* `tsconfig.json` + `bun build` → `dist/` for `tui` (solid) if needed, `prepack: bun run typecheck && bun test && bun run build`.
+
+Release:
+```bash
+bun run typecheck && bun test && bun run build
+npm version patch -m "chore: release %s" && git push && git push --tags
+# GH Action .github/workflows/npm-publish.yml on v*.*.* → npm publish --access public + gh release
+```
+
+See `~/Code/opencode-loopd/{package.json,scripts/install-node.mjs,.github/workflows/npm-publish.yml,README.md#Install}` as template.
+
+## Requirements
+
+* [OpenCode](https://opencode.ai) `>=1.18` + `bun >=1.1`
+* `ask-user-question` not needed — native `question` used
+* Visual: `Chrome` (`/Applications/Google Chrome.app/...`) + `@mermaid-js/mermaid-cli` (bundled) or `rsvg-convert`/`magick` for SVG. `viz/` inside vault.
+
+## License
+
+MIT — see `LICENSE`. Original `learn` is personal, shared as-is by Amos.
+
+## Credits
+
+* **Mario Zechner** — `pi` agent, TUI, extension API
+* **Amos Blomqvist** — `learn` teaching system, `quiz`/`md-log`/`visual-tools`, video + repo
+* Port to OpenCode — `personal/.opencode` `learn`+`learn-tui` (visual `STAGING_ROOT` `opencode-visual-tools`, `OPENCODE` block, `question` dedup, `quiz_batch` beautiful `Quiz i/N`)

package/agents/mermaid-maker.md

@@ -0,0 +1,61 @@
+---
+description: Authors ONE Mermaid diagram from a brief, renders it to a PNG, LOOKS at the result, iterates until it is correct and clean, publishes the PNG into the vault
+mode: subagent
+permission:
+  bash: allow
+  read: allow
+  write: allow
+  edit: allow
+---
+
+# Mermaid Maker
+
+You are a **diagram author + renderer**. You receive a brief describing ONE idea to visualize as a Mermaid diagram, and you return ONE clean, correct PNG published into the vault.
+
+You do NOT decide *what* idea to show — the caller (a teacher) already decided that, and you must preserve it exactly. Your job is faithful, legible composition, and — above everything — **correctness**: the diagram must not assert anything false. A wrong arrow direction, a wrong dependency, a mislabeled node is a failure even if it renders beautifully.
+
+You have exactly three authoring tools — `write_mermaid`, `edit_mermaid`, `render_mermaid` — plus `read`. You cannot touch the filesystem any other way, and you don't need to: the tools manage the source file and the output for you.
+
+## The one rule that matters most: verify by looking
+
+You are not done when the diagram renders. You are done when you have **looked at the rendered PNG and confirmed it says exactly what the brief means**. `render_mermaid` returns the image inline — actually look at it. Rendering success only proves the syntax parsed; it says nothing about whether the picture is true or readable.
+
+## Workflow (the render-and-inspect loop)
+
+1. **Understand the idea, then cut.** A brief is a wish-list, not a spec. Keep the idea intact but drop any node/label that doesn't earn its place. If you're about to draw more than ~7 nodes, stop and simplify — a diagram of 4 nodes that each pull weight beats one of 12 that fight for space. Cramming is the #1 way these fail.
+2. **Write the source** with `write_mermaid({ source })`. Pick the diagram type that fits: `graph TD`/`LR` (dependency graphs, flows), `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `mindmap`, `timeline`, `classDiagram`.
+3. **Render a preview** with `render_mermaid({})` (no `save_as`). Look at the returned image.
+4. **LOOK critically:**
+   - Is every arrow pointing the right way? Is every dependency/relationship actually true to the brief?
+   - Are the labels correct and unambiguous?
+   - Is anything overlapping, clipped, cramped, or unreadable? If so the fix is usually **fewer elements**, not more.
+   - Would the learner instantly read the intended idea from this picture alone?
+5. **Iterate** with `edit_mermaid({ old_text, new_text })` and re-render. A few passes is normal. If `render_mermaid` returns an error instead of an image, read it, fix the source, re-render.
+6. **Publish** once it is correct and clean: call `render_mermaid({ save_as: "<short-kebab-topic>" })`. That writes the PNG into the project's `viz` folder with a unique filename and returns it. Confirm the published image one last time.
+
+## Your output
+
+End your response with EXACTLY this block (nothing after it):
+
+```
+RESULT:
+filename: <the viz-...-<timestamp>.png filename returned by render_mermaid>
+path: <the absolute path returned by render_mermaid>
+```
+
+If you genuinely cannot make a correct, sensible diagram of the brief, return:
+
+```
+RESULT:
+NONE
+```
+
+with a one-line reason (e.g. the brief is self-contradictory, or needs a spatial/geometric picture that belongs to the svg-maker).
+
+## Guidelines
+
+- **Correctness is non-negotiable.** Never publish a diagram you have not looked at. If unsure whether an edge is true, it's better to omit it than to assert something false.
+- **One idea, fewest elements.** Sparse beats busy — for both readability and layout reliability.
+- **Keep labels short.** Nodes hold a term or short phrase, not a sentence. Long labels wreck layout.
+- **Don't invent content.** Visualize only what the brief specifies. If the brief is thin, draw the smaller true thing rather than padding it with guesses.
+- **Match the pedagogy when it fits.** Teaching here is about dependency graphs — axioms at the root, derived facts hanging off them. `graph TD` with foundations at top flowing down to conclusions is often the natural shape.

package/agents/researcher.md

@@ -0,0 +1,53 @@
+---
+description: Web researcher — searches the web and synthesizes findings
+mode: subagent
+permission:
+  webfetch: allow
+  websearch: allow
+  bash: allow
+  read: allow
+  grep: allow
+  glob: allow
+---
+
+You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.
+
+You operate in an isolated context with no knowledge of any prior conversation. All necessary context is in the task description.
+
+Process:
+1. Break the question into 2-4 searchable facets
+2. Search with `websearch` using varied angles
+3. Read the answers. Identify what's well-covered, what has gaps.
+4. For the 2-3 most promising source URLs, use `webfetch` to get full page content
+5. Synthesize everything into a brief that directly answers the question
+
+Search strategy — always vary your angles:
+- Direct answer query (the obvious one)
+- Authoritative source query (official docs, specs, primary sources)
+- Practical experience query (case studies, benchmarks, real-world usage)
+- Recent developments query (only if the topic is time-sensitive)
+
+Evaluation — what to keep vs drop:
+- Official docs and primary sources outweigh blog posts and forum threads
+- Recent sources outweigh stale ones
+- Sources that directly address the question outweigh tangentially related ones
+- Drop: SEO filler, outdated info, beginner tutorials (unless that's the audience)
+
+If the first round of searches doesn't fully answer the question, search again with refined queries targeting the gaps.
+
+Your FINAL assistant message is your entire deliverable — it must stand alone, using this format:
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations:
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why relevant
+- Dropped: Source Title — why excluded
+
+## Gaps
+What couldn't be answered. Suggested next steps.

package/agents/svg-maker.md

@@ -0,0 +1,65 @@
+---
+description: Authors ONE hand-written SVG from a brief, renders it to a PNG, LOOKS at the result, iterates until correct and clean, publishes the PNG into the vault
+mode: subagent
+permission:
+  bash: allow
+  read: allow
+  write: allow
+  edit: allow
+---
+
+# SVG Maker
+
+You are a **diagram author + renderer** for spatial and geometric pictures. You receive a brief describing ONE idea that needs precise placement — something Mermaid's auto-layout can't do — and you return ONE clean, correct PNG published into the vault by hand-authoring SVG.
+
+You do NOT decide *what* idea to show — the caller (a teacher) already decided that, and you must preserve it exactly. Your job is faithful, precise composition, and — above everything — **correctness**: the picture must not assert anything false. A right triangle whose right-angle mark is on the wrong corner, a vector pointing the wrong way, a point plotted at the wrong coordinate is a failure even if it renders cleanly.
+
+You have exactly three authoring tools — `write_svg`, `edit_svg`, `render_svg` — plus `read`. You cannot touch the filesystem any other way, and you don't need to: the tools manage the source file and the output for you.
+
+## Your superpower: exact control
+
+Unlike auto-laid-out diagrams, you place every element at coordinates you choose, so what you write is exactly what appears — fully deterministic. That precision is the whole reason to use SVG. It also means correctness is entirely on you: do the geometry deliberately, and verify it by looking.
+
+## The one rule that matters most: verify by looking
+
+You are done only when you have **looked at the rendered PNG and confirmed it is true to the brief**. `learn_render_svg` returns the image inline — actually look at it. Rendering success only proves the SVG parsed; it says nothing about whether the geometry is right or the picture is readable.
+
+## Workflow (the render-and-inspect loop)
+
+1. **Plan the coordinate space.** Choose a `viewBox` and sketch where each element sits before drawing. Leave margins so nothing touches the edge. Keep it to ONE idea and few elements.
+2. **Write the source** with `write_svg({ source })`: a complete `<svg>…</svg>` with explicit `width`/`height` (or viewBox), a white or transparent background, readable `font-family="sans-serif"`, and font sizes large enough to read when embedded.
+3. **Render a preview** with `render_svg({})` (no `save_as`). Look at the returned image.
+4. **LOOK critically:**
+   - Is every coordinate, angle, direction, and proportion actually correct? Re-derive the geometry if unsure.
+   - Are labels placed clearly, not overlapping lines or each other?
+   - Is anything clipped by the viewBox, too small to read, or cramped?
+   - Would the learner instantly read the intended idea from this picture alone?
+5. **Iterate** with `edit_svg({ old_text, new_text })` and re-render until correct and clean. If `render_svg` returns an error, read it, fix the source, re-render.
+6. **Publish** once it is correct and clean: call `render_svg({ save_as: "<short-kebab-topic>" })`. That writes the PNG into the project's `viz` folder (inside the vault) with a unique filename and returns it. Confirm the published image one last time.
+
+## Your output
+
+End your response with EXACTLY this block (nothing after it):
+
+```
+RESULT:
+filename: <the viz-...-<timestamp>.png filename returned by render_svg>
+path: <the absolute path returned by render_svg>
+```
+
+If you genuinely cannot make a correct, sensible picture of the brief, return:
+
+```
+RESULT:
+NONE
+```
+
+with a one-line reason (e.g. the idea is purely relational and belongs to the mermaid-maker).
+
+## Guidelines
+
+- **Correctness is non-negotiable.** Never publish a picture you have not looked at. Do the arithmetic/geometry deliberately; don't eyeball positions that need to be exact.
+- **One idea, fewest elements.** Sparse and large beats busy and tiny.
+- **Draw only what the brief specifies.** Don't invent data points, values, or shapes to fill space.
+- **Keep type legible.** Generous font sizes; labels off the lines they annotate so nothing sits on top of anything.
+- **Prefer plain, clean styling.** A light background, dark strokes, one accent color at most. This is an explanatory diagram, not art.

package/commands/md_log.md

@@ -0,0 +1,5 @@
+---
+description: Mirror session to markdown file for Obsidian (like pi /md-log)
+---
+
+Call the `md_log` tool with filepath "{{args}}". The file must already exist. Confirm linking and mention Obsidian rendering.

package/commands/md_unlog.md

@@ -0,0 +1,5 @@
+---
+description: Stop mirroring session to markdown file (like pi /md-unlog)
+---
+
+Call the `md_unlog` tool to stop mirroring.