fix(images): write note-relative image links in sources pages

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.

[Aldominguez12]

Problem

Short-doc source pages live at wiki/sources/<doc>.md but embedded their images with wiki-root-relative links (![image](sources/images/<doc>/file.png)). Markdown renderers resolve links relative to the containing file — Obsidian, GitHub, VS Code — so from a sources page every image resolved to the non-existent wiki/sources/sources/images/... and rendered broken. This breaks the "Opens in Obsidian" integration promised in the README for any document with figures.

Fix

• New md_image_ref() helper emits note-relative images/<doc>/... links, used by the three .md-visible writers (convert_pdf_with_images, extract_base64_images, copy_relative_images). These resolve correctly in Obsidian, GitHub, and VS Code.
• Long-doc JSON page metadata keeps wiki-root-relative paths: it is internal, consumed by get_wiki_page_content / read_wiki_image against the wiki root. The two conventions are now documented explicitly in the docstrings.
• read_wiki_image() retries note-relative paths under sources/, so agents can pass image paths verbatim as seen in either surface.
• Query/skill-factory prompts and the openkb skill's wiki-schema.md updated to describe both path forms.

Notes

Already-ingested KBs keep their old-style links (the read_wiki_image fallback keeps agent flows working, but renderers still show them broken). A migration helper for existing sources pages would be a natural follow-up — happy to send it if there's interest.

Verification

• Updated tests/test_images.py expectations plus new TestNoteRelativeResolution (generated links must resolve from wiki/sources/<doc>.md on disk) and TestReadWikiImage (both path forms, not-found, path escape).
• pytest tests/test_images.py tests/test_agent_tools.py tests/test_converter.py tests/test_indexer.py tests/test_query.py tests/test_skill_creator.py tests/test_skill_tools.py tests/test_chat_session.py green; ruff check/format and mypy clean on the touched modules.

🤖 Generated with Claude Code

[KylinMountain]

Thanks @Aldominguez12 — a clean, well-tested fix that gets image rendering right across Obsidian/GitHub/VS Code without breaking existing KBs; I'd happily take the migration helper for already-ingested pages as a follow-up.