Skip to content

v1.1.0 - Synthadoc Community Edition

Choose a tag to compare

View all tags
@william-Johnason william-Johnason released this 20 Jul 17:54
v1.1.0
4cab608
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Synthadoc Community Edition v1.1.0 Release Notes

Synthadoc Community Edition v1.1.0 is released.

v1.1.0 ships five major features that deepen the knowledge graph experience, bring first-class support for every major AI coding tool, and let you capture knowledge that was previously ephemeral.

Installation / Upgrade

New install

pip install synthadoc
synthadoc --version   # should print 1.1.0

synthadoc install history-of-computing --target ~/wikis --demo

Then follow the Quick-Start Guide to start the engine.

Upgrade from an existing install

pip install synthadoc --upgrade     # upgrade the Python package
synthadoc plugin upgrade            # push updated plugin to all registered wikis
synthadoc demo sync --force         # update demo wiki files to latest template

Database migration: audit.db schema is migrated automatically on server start to version 3 (adds edge_type column to graph_edges). No manual steps required.

Existing wikis: new agent skill files: If your wiki was created before v1.1.0, run synthadoc scaffold once to generate CLAUDE.md and GEMINI.md alongside the existing AGENTS.md:

synthadoc scaffold -w <your-wiki>

What's New in v1.1.0

1. Multi-Platform Agent Skill Files (CLAUDE.md, AGENTS.md, GEMINI.md)

Every Synthadoc wiki now ships with three agent skill files at the wiki root — one for each major AI coding platform:

File Read by
AGENTS.md Codex CLI, OpenCode, generic OpenAI-Agents tooling
CLAUDE.md Claude Code (loaded automatically when the folder is open)
GEMINI.md Gemini CLI

All three files carry the same LLM-generated content: domain guidelines specific to your wiki, a quick-reference CLI command table, and the full Synthadoc MCP tool list. The domain guidelines are regenerated from your actual wiki pages every time you run synthadoc scaffold, so they stay accurate as the wiki grows.

Value: You no longer need to configure or brief your AI coding tool about what Synthadoc does or how to interact with your wiki. Open the wiki folder in Claude Code, Codex, or Gemini CLI and it reads the instructions automatically.

→ See Design §33 — Multi-Platform Agent Skill Files

2. Session History Ingestion (.jsonl)

AI coding sessions: debugging discussions, architecture reviews, code walk-throughs — contain knowledge that is never written down anywhere. When the session ends, it's gone.

The new session skill ingests any .jsonl file from Claude Code, Codex CLI, or Cursor directly into your wiki:

# Ingest your most recent Claude Code session
synthadoc ingest ~/.claude/projects/-Users-yourname-workspace-my-project/<session-id>.jsonl

What gets extracted:

  • User messages (≥ 3 words) : the problems and questions you brought to the session
  • Assistant answers (≥ 20 words) : explanations, decisions, code walk-throughs

What gets filtered out automatically: tool call output (file reads, shell commands), thinking blocks, sub-agent scaffolding, and session metadata lines. Credentials and file contents in tool output are never included.

The resulting wiki page slug is auto-derived from the session date and the first substantive user message — for example, session-2026-07-15-how-do-i-implement-sliding.

Value: Session knowledge becomes searchable, linkable, and citable alongside your other sources. When you later ask the wiki about a topic you discussed in a session, the session page can appear in the answer with a citation.

Standalone use: no wiki or server required. The session skill can also be installed as a standalone Claude Code skill. No Synthadoc wiki, no running server. Each skill can be installed individually or as a full set, and runs entirely from its own dependencies:

npx -y skills add axoviq-ai/synthadoc --skill session --agent claude-code

→ Skill reference: synthadoc/skills/session/SKILL.md
→ Full walkthrough: Quick-Start Guide §25 — Ingest an AI session transcript
→ Design: §5 Skills System — Session Skill

3. Weighted Knowledge Graph Edges (co-source + wikilink)

The knowledge graph now distinguishes and weights two types of relationships between pages:

Edge type What it means Weight contribution
wikilink Page A links to[[page-b]] in its body +1 per occurrence
co_source Both pages were compiled from the same source file +2 per shared source
mixed Both wikilink and co-source relationships exist sum of both

Co-source edges appear immediately after ingest — before any explicit wikilinks are created — surfacing hidden relationships between pages that came from the same document. A dashed edge line marks pure co-source connections in both the web UI and Obsidian panel.

Edge thickness in both graph views is proportional to weight (thicker = stronger connection).

This is a non-breaking schema upgrade: graph_edges gains an edge_type column (schema version 3, auto-migrated on server start). Existing wikis need one lint run to rebuild the graph with the new weights:

synthadoc lint run -w <your-wiki>

→ Design: §32 Knowledge Graph

4. Obsidian Knowledge Graph Panel

The Obsidian plugin now includes a dedicated knowledge graph panel — open it from the command palette with "Graph: show knowledge graph" (Ctrl/Cmd+P).

Features:

  • Canvas 2D force-directed graph: Verlet integration (no external library, loads instantly)
  • Draggable panel: drag the header to reposition; click the × to close
  • Type filter: narrow to a specific knowledge type (concept, person, event…)
  • Cluster legend: colored badges matching the Louvain cluster assignments
  • Hover tooltip: shows title, slug, type, lifecycle state, cluster ID, and connection count
  • Click to open: clicking a node opens the wiki page in the current Obsidian pane
  • Node drag: drag nodes to repin them to a new position
  • 300-node cap: for large wikis, shows the 300 most-connected pages with an explanatory banner; use the type filter to narrow the view

When to use the Obsidian panel vs. the web UI:

I want to… Use
Navigate to and edit a wiki page I found in the graph Obsidian panel
Ask a question about a page I clicked in the graph Web UI Graph tab → "Ask about this →"

Rule of thumb: Use the web UI when you want to ask questions about a node. Use the Obsidian panel when you want to navigate to and edit a page.

→ Walkthrough: Quick-Start Guide §24 — Knowledge Graph
→ Design: §8 Obsidian Plugin

5. Synthadoc Scaffold Marker (per-section purpose.md protection)

The existing single <!-- synthadoc:scaffold --> marker in index.md that protects your custom intro text now works per-section inside wiki/purpose.md.

Each ## Section in purpose.md can have its own marker. Text you write above the marker in any section is preserved on every scaffold run. Text below the marker is refreshed with new LLM output. Sections where you have not added a marker are fully refreshed (same as before).

## Overview

My organization-specific context for this wiki.

<!-- synthadoc:scaffold -->

LLM-generated overview — refreshed each scaffold run.

## What Belongs

<!-- synthadoc:scaffold -->

Entirely LLM-managed — no custom note above.

This is especially useful when your domain requires stable scope definitions that the LLM should not paraphrase away, while still keeping the rest of purpose.md current with the growing wiki.

→ Walkthrough: Quick-Start Guide §14 — Scaffold Marker
→ Design: §34 Synthadoc Scaffold Marker

Bug Fixes and Improvements

  • System pages excluded from knowledge graph: overview, index, dashboard, purpose, and log are no longer included as graph nodes. They linked to nearly every page and distorted Louvain cluster detection. Both the Obsidian panel and the web UI reflect this exclusion. Wikis that previously showed more nodes than actual pages (e.g. 17 nodes vs. 13 pages) will now display the correct count after one lint run.
  • Web UI graph cluster legend: the Graph tab now shows a cluster legend below the canvas (matching the Obsidian plugin panel), with a color swatch and label for each Louvain cluster in the current filter.
  • Source deduplication on re-ingest: re-ingesting a source file that was already recorded in a page (for example, a .jsonl session that grew since the last ingest) now replaces the page body rather than appending a duplicate section. Absolute vs. relative path variants of the same file are recognized and de-duplicated correctly.
  • purpose.md domain label inference: scaffold now infers a precise domain label from wiki content (e.g. History of Computing) and uses it in all three agent skill files, replacing generic placeholder text.
  • Obsidian graph panel modal-only close: the graph panel closes only when the × button is clicked. Escape key and outside-click do not dismiss it (consistent with the Query and Lifecycle modals). The panel can be dragged to any screen position, with viewport boundary clamping so it cannot be dragged off-screen.
  • Knowledge graph edge weight correctness: mixed edges (pages with both a wikilink and a shared source) now report the correct combined weight. Previously, when a wikilink ran in the opposite direction from the canonical co-source edge, max() was used to resolve the collision instead of summing the two contributions. For example, a page pair with one wikilink (+1) and one shared source (+2) would show weight 2 instead of 3. All edge weights are now accurate; run synthadoc lint run once to rebuild the graph after upgrading.
  • CI: Windows sync runner fix: scripts/sync_plugin.py and scripts/sync_web_ui.py now use shutil.copy2 instead of cp -f, resolving CI failures on Windows runners.
  • synthadoc status lifecycle count mismatch: the active/archived breakdown in synthadoc status summed to more pages than the total page count. The /lifecycle/status endpoint was not applying the system-page exclusion filter (overview, index, dashboard, purpose, log), so system pages that had audit DB entries leaked into the lifecycle summary. The total page count was always correct; the per-state breakdown now matches it.
  • Knowledge graph re-includes archived pages after server restart: cascade_archive() correctly deletes a page's graph node at archive time, but _build_graph() (called on server restart or full lint run) read all .md files from disk without filtering by lifecycle state, causing archived pages to reappear as isolated nodes. The graph now uses an explicit allowlist: only active, stale, and contradicted pages appear as nodes. Draft pages (unreviewed content) and archived pages (retired) are excluded from the knowledge graph on every build.
  • Graph node/edge count scope now visible: both the web UI Graph tab and the Obsidian knowledge graph panel now display (excludes draft and archived nodes) next to the node and edge count, making the scope of the graph immediately clear without requiring the user to hover or dig into documentation.
  • Stray CJK characters in history-of-computing demo: isolated Chinese words (最早的, 贡献, 计算) left by LLM generation artifacts in the English demo wiki pages alan-turing.md and programming-languages-overview.md were removed.

Full Changelog

See Appendix A — Release Feature Index in the design document for the complete version-by-version feature list.

Commits since v1.0.2:

  • 17835b7 fix(graph): sum edge weights when merging undirected pair directions
  • 53f08f4 fix(graph,ingest,plugin): 5 code review findings for v1.1.0
  • f9d3a8b feat(web-ui): add cluster legend to knowledge graph panel
  • 45adebb fix(graph): exclude system pages from knowledge graph
  • 7acf497 feat(obsidian graph plugin): knowledge graph panel
  • 9c7e222 feat(Knowledge Graph): Weighted Edges, Smart Labels & Adaptive Layout
  • 3d33cb1 chore(skills): register session skill
  • 24abd7e feat(session history ingestion): ingest AI coding session transcripts
  • 6562bb8 fix(purpose.md): per-section markers + domain_label inference
  • f1cee3d feat: multi-platform agent skill files + README capability links + CI Windows fix

Acknowledgements

Built and maintained by the Synthadoc team.

Assets 2
Loading