README
¶
yomihon
yomihon is a local, single-user web interface for reading and curating a
personal Markdown knowledge vault. It renders notes and other browsable,
non-hidden regular files as calm, navigable pages and keeps the human decision
at the center: read a note, understand its context, then advance its lifecycle
status without turning the reader into another editor.
[!WARNING] yomihon is under active development. Expect significant feature and interface changes before the first stable release.
What it does
- Renders Markdown, wikilinks, transclusions, callouts, ruby, Mermaid, source files, images, PDFs, and HTML reports as a focused reading surface.
- Builds navigation, backlinks, a table of contents, and local lexical search from the current vault snapshot.
- Presents study paths, lesson tools, vault diagnostics, and concept coverage without changing the underlying notes.
- Offers diagnostic and search commands for local agents, with semantic retrieval available only as an explicit, user-authorized CLI action.
- Advances one note's
statusthrough the vault's own lifecycle rules and records the accepted transition as one git commit.
Boundaries
- One vault write. Yomihon may update only the frontmatter
statusfield. Every other vault byte remains read-only. - Local by default. The web server has no authentication and listens only
on
127.0.0.1. Ordinary reading and search stay local; provider egress requires an explicit semantic or certification action and the operator's own credential. - The vault owns its contract. Schema, privacy, navigation, and lifecycle
capabilities come from
System/schemas/vault-schema.toml, never a hidden copy in the binary. - Problems stay visible. Invalid metadata and broken or ambiguous links become diagnostics. The renderer never guesses or repairs source content.
Getting started
Requires Go 1.26.5 or newer.
Every vault needs its own contract at
System/schemas/vault-schema.toml. The repository includes a parser-gated
starting point at examples/vault-schema.toml.
Copy and deliberately adapt it before serving real content. Yomihon diagnoses
a missing or invalid contract but never creates or edits one.
Install the command:
go install github.com/koopa0/yomihon/cmd/yomihon@latest
Every asset the reader serves — stylesheet, client modules, fonts, the Mermaid runtime — is compiled into that binary, so it runs anywhere without the repository beside it.
Read a vault:
yomihon serve --root /path/to/vault
# http://127.0.0.1:9610
yomihon help lists every command, and yomihon <command> --help explains one.
The vault path may also come from the environment, which is what a shell alias
or a launch agent will usually set; --root wins when both are given.
| Variable | Purpose | Default |
|---|---|---|
YOMIHON_ROOT |
Vault path | ~/obsidian |
YOMIHON_PORT |
Listen port | 9610 |
YOMIHON_EMBED_KEY |
User-owned Gemini credential for an explicit semantic CLI action | unset |
A successful start logs yomihon serving and Home loads at that address. An
invalid vault path exits non-zero with a yomihon exited error; a missing or
invalid vault contract is warned, keeps reading available, and closes the write
face.
The listener address is fixed; only the port is configurable. Reading, navigation, diagnostics, and lexical search support macOS, Linux, and Windows. Status writes and semantic generations currently support macOS and Linux.
Yomihon is a personal application rather than a turnkey multi-user service.
It is deliberately not distributed as a container image: the listener binds
127.0.0.1 in the process's own network namespace, which inside a container is
a loopback the host cannot reach, and the status write runs git as the
operator so the commit carries their identity. Both are the boundary working,
and both would have to be loosened to make an image useful. Use
GitHub Issues for questions and
defects.
License
MIT. Redistributed fonts and client assets are documented in THIRD_PARTY_NOTICES.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets embeds yomihon's small, fixed set of vendored and hand-written client-side files.
|
Package assets embeds yomihon's small, fixed set of vendored and hand-written client-side files. |
|
cmd
|
|
|
yomihon
command
yomihon is the local reading-and-adjudication interface for the Obsidian vault.
|
yomihon is the local reading-and-adjudication interface for the Obsidian vault. |
|
internal
|
|
|
asset
Package asset serves yomihon's fixed, compile-time-known set of static files: the vendored mermaid ES-module runtime, yomihon's own fixed native client-module graph, the canonical brand mark, and the generated chroma stylesheet.
|
Package asset serves yomihon's fixed, compile-time-known set of static files: the vendored mermaid ES-module runtime, yomihon's own fixed native client-module graph, the canonical brand mark, and the generated chroma stylesheet. |
|
graph
Package graph builds the wikilink resolution index: every markdown note's filename, path, and alias forms, normalized identically at index-build time and lookup time.
|
Package graph builds the wikilink resolution index: every markdown note's filename, path, and alias forms, normalized identically at index-build time and lookup time. |
|
judge
Package judge implements the vault diagnostics behind the check, exists, and coverage commands, and their JSONL wire format.
|
Package judge implements the vault diagnostics behind the check, exists, and coverage commands, and their JSONL wire format. |
|
lesson
Package lesson loads the hand-authored data that enriches lesson reading pages: Japanese slot-machine sentence patterns from System/slots/*.yaml and the cross-domain concept-note index used by in-page sheets.
|
Package lesson loads the hand-authored data that enriches lesson reading pages: Japanese slot-machine sentence patterns from System/slots/*.yaml and the cross-domain concept-note index used by in-page sheets. |
|
nav
Package nav builds the vault's read-only navigation model.
|
Package nav builds the vault's read-only navigation model. |
|
note
Package note owns the general reading surface: Home, rendered notes, raw bytes, and the honest fallback page for vault files without a dedicated reader.
|
Package note owns the general reading surface: Home, rendered notes, raw bytes, and the honest fallback page for vault files without a dedicated reader. |
|
origin
Package origin enforces the browser's same-origin resource boundary for every response served by yomihon's loopback reading site.
|
Package origin enforces the browser's same-origin resource boundary for every response served by yomihon's loopback reading site. |
|
render
Package render owns projections of Obsidian-dialect markdown.
|
Package render owns projections of Obsidian-dialect markdown. |
|
report
Package report serves the reports face: the daily-briefing HTML under System/reports/, presented verbatim inside a sandboxed iframe.
|
Package report serves the reports face: the daily-briefing HTML under System/reports/, presented verbatim inside a sandboxed iframe. |
|
schema
Package schema loads the vault's machine-readable contract (System/schemas/vault-schema.toml) and answers status state-machine questions.
|
Package schema loads the vault's machine-readable contract (System/schemas/vault-schema.toml) and answers status state-machine questions. |
|
search
Package search is the vault's in-memory search index and query engine.
|
Package search is the vault's in-memory search index and query engine. |
|
search/agent
Package agent implements privacy-gated, agent-facing search.
|
Package agent implements privacy-gated, agent-facing search. |
|
search/evalset
Package evalset owns and evaluates the committed synthetic semantic-search regression set without embedding text or opening a network connection.
|
Package evalset owns and evaluates the committed synthetic semantic-search regression set without embedding text or opening a network connection. |
|
search/evalset/recording
Package recording validates the local vector artifact for the synthetic semantic-search evaluation corpus.
|
Package recording validates the local vector artifact for the synthetic semantic-search evaluation corpus. |
|
search/semantic
Package semantic owns the optional semantic retrieval channel: corpus chunking, provider egress, immutable vector generations, and exact ranking.
|
Package semantic owns the optional semantic retrieval channel: corpus chunking, provider egress, immutable vector generations, and exact ranking. |
|
search/semantic/observer
Package observer owns the committed, content-free query-vector workload used to measure production semantic top-k latency.
|
Package observer owns the committed, content-free query-vector workload used to measure production semantic top-k latency. |
|
shell
Package shell projects the navigation and lifecycle state shared by every full-page reading surface.
|
Package shell projects the navigation and lifecycle state shared by every full-page reading surface. |
|
snapshot
Package snapshot owns the reading server's coherent vault generations.
|
Package snapshot owns the reading server's coherent vault generations. |
|
status
Package status is the write face: the only package in this repo allowed to write vault files or run git.
|
Package status is the write face: the only package in this repo allowed to write vault files or run git. |
|
syllabus
Package syllabus serves the study-path page: a full-page render of one parsed study-path tree, with a switcher across every study-path in the vault.
|
Package syllabus serves the study-path page: a full-page render of one parsed study-path tree, with a switcher across every study-path in the vault. |
|
ui/pages
templ: version: v0.3.1020
|
templ: version: v0.3.1020 |
|
vault
Package vault reads notes from the Obsidian vault on disk.
|
Package vault reads notes from the Obsidian vault on disk. |