Skip to content

v1.2.1 - Synthadoc Community Edition

Choose a tag to compare

View all tags
@william-Johnason william-Johnason released this 13 Aug 18:26
· 50 commits to main since this release
v1.2.1
e0c77c7
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.2.1 Release Notes

Synthadoc Community Edition v1.2.1 is released.

Summary

This release ships three new agentic maintenance workflows based on the pluggable workflow architecture introduced in v1.2.0, as well as a set of targeted fixes across schedulers, web interfaces, audit databases, and snapshot displays. In addition to being conversational, the new workflows follow the same confirm-before-act pattern as the existing re-ingest workflows.

✨ New: Agentic Maintenance Workflows (Workflow C, D, E)

v1.2.0 introduced the agentic ingest-and-lint loop with two workflows: bulk stale-page reingest (A) and page-by-slug reingest (B). v1.2.1 adds three more, all accessible from the web chat UI, the Obsidian query modal, and the synthadoc query CLI.

Workflow C: Broken Wikilinks Scan and Fix

Trigger phrases: "scan for broken wikilinks", "fix broken links", "check wikilink integrity"

Scans all active pages for [[slug]] references that resolve to no existing page. Uses Python stdlib difflib.get_close_matches to propose fuzzy corrections for likely typos (e.g. [[alan-tunring]] → [[alan-turing]]). Broken links with no close match are unlinked — markup removed while display text is preserved. Presents the full fix scope for confirmation before writing anything, then runs a lint pass to validate link integrity.

Tools: find_broken_wikilinks → confirm → apply_link_fixes × N → run_lint → poll_job → get_page_states

If the wiki is already clean, the workflow stops after scanning, abd no confirmation card appears and no changes are made.

Workflow D: Lint Run and Full Report

Trigger phrases: "run lint", "run a full lint check"

A full lint pass is run and the full report is streamed in one conversational turn, no confirmation gate is required (lint is read-only).The report includes dangling links removed, orphan pages, contradictions (resolved and flagged), contradicted page slugs with state-change dates, adversarial warnings by slug and count, and all orphan slugs.Runs a full lint pass and streams the complete report in one conversational turn, no confirmation gate needed (lint is read-only). Reports dangling links removed, orphan pages, contradictions (resolved and flagged), contradicted page slugs with state-change dates, adversarial warnings by slug and count, and all orphan slugs.

Tools: run_lint → poll_job → get_lint_report

Tip: Use Workflow D to get a full picture first, then follow up: "scan for broken wikilinks" or "re-ingest stale pages" in the same session.

Workflow E : Scaffold Regeneration

Trigger phrases: "run scaffold", "rebuild scaffold", "regenerate scaffold"

Previews the domain and the files that will be overwritten, requires confirmation before writing, then regenerates wiki/index.md, wiki/purpose.md, AGENTS.md, CLAUDE.md, and GEMINI.md. ROUTING.md is regenerated only if it already exists. User-written content above <!-- synthadoc:scaffold --> markers is always preserved.

Tools: get_scaffold_preview → confirm → run_scaffold

Pluggable architecture

All five workflows share a common AgenticWorkflow base class. The workflow registry (synthadoc/agents/workflows/_registry.py) holds an ordered list of workflow classes; each declares a MATCH_RE for fast-path pre-LLM routing. The action agent builds _ROUTED_PAT dynamically from ROUTED_WORKFLOWS at import time, adding a new workflow requires three lines of code (new module + one import + one registry entry) and no changes to any other file.

Business value: Wiki maintenance that previously required manual CLI commands — checking for dead links, regenerating scaffold after large ingest batches, reviewing the full lint state — can now be driven conversationally from the same chat interface used for querying. The confirm-before-act gate ensures the agent never modifies the wiki without explicit user approval, keeping the experience predictable. The pluggable architecture means future workflows (e.g. an orphan-page fix workflow, a citation audit workflow) can be added without touching the routing infrastructure.

→ Demo walkthrough: §26 Agentic Maintenance Workflows
→ Architecture detail: § Agentic Maintenance Workflows

✨ New: get_page_states step in agentic reingest

Workflows A and B (the v1.2.0 reingest workflows) now finish with a get_page_states call that returns the final lifecycle state (active, stale, draft, archived, unknown) of every re-ingested page. The completion summary includes a per-page state column with ✓ active, ✗ stale, and ○ other, making it immediately clear whether each re-ingest succeeded in promoting the page to active. (PR #303)

✨ New: Agentic workflow routing via synthadoc query CLI

All five agentic maintenance workflows are now accessible from the synthadoc query CLI command, the same routing path used by the web UI chat. The CLI prints inline tool_progress events to stdout as each step completes. (PR #300)

Now all five agentic maintenance workflows are accessible via the synthadoc query CLI command, the same path used by the web UI chat. The CLI prints inline tool_progress events to stdout as each step completes. (PR #300)

🐛 Fixes

Audit DB: secondary indexes on high-traffic tables (PR #312)

audit_events, lifecycle_events, and claim_citations were missing secondary indexes on their most-queried columns (foreign key joins and timestamp ranges). Large audit databases with thousands of events incurred full-table scans on every Audit modal page load and every GET /audit/events call. Secondary indexes are now created at server startup via CREATE INDEX IF NOT EXISTS — no migration step required.

Web UI: auto-scroll during agentic workflow progress (PR #308)

The web UI content panel did not scroll to the bottom as new tool_progress SSE events arrived during a workflow run. Users had to scroll manually to see each step. The panel now auto-scrolls to the bottom after every streamed event, keeping progress visible without user interaction.

Web UI: pre_prompt suggestion cleared after use (PR #306)

After an agentic workflow completed with a done.pre_prompt suggestion (e.g. "Run lint to promote re-ingested pages to active"), sending that suggestion pre-filled the textarea again on the next turn. The pre_prompt field is now cleared after the user sends the suggested action.

Scheduler: subprocess pipe draining on kill/timeout (PR #307)

When a scheduled subprocess was killed (due to timeout or cancellation), the scheduler closed the pipes before draining stdout/stderr, causing BrokenPipeError log noise and, on Windows, occasional hangs waiting for the child to acknowledge the pipe close. The scheduler now drains both pipes after sending the kill signal before proceeding.

Snapshot timestamps displayed in local time (PR #304)

Content snapshot timestamps in the Obsidian Content Snapshots tab and the synthadoc lifecycle history CLI output were displayed in UTC regardless of the user's timezone. Timestamps are now converted to the local timezone before display.

📹 Demo video & 📝 Blog post

A new YouTube walkthrough covers the full agentic maintenance workflow — manufacturing a stale page, triggering the re-ingest workflow from the web UI chat, confirming the operation, and following the progress stream through to the lint run and promotion.

▶ Agentic Maintenance Workflow

The design thinking behind the tool-call loop architecture — why a pluggable workflow registry beats hard-coded routing, how the confirm-before-act gate keeps the agent predictable, and where the approach fits in the broader agentic-tooling landscape — is covered in the accompanying blog post:

📝 The Tool-Call Loop: Building Adaptive Maintenance Workflows into LLM Wiki

Upgrade

pip install --upgrade synthadoc
synthadoc plugin upgrade       # push updated Obsidian plugin to all registered wikis
synthadoc demo sync --force    # update demo assets

Commits since v1.2.0

SHA Description
10fff6a chore(v1.2.1): release prep — version bump, docs, badges, plugin sync
142ef4c docs: trim §26 agentic workflows to demo-first; update design.md routing architecture
715fb7c feat(v1.2.1): agentic maintenance workflows — Lint Report, Broken Wikilinks, and Scaffold (#313)
5d7882b fix(audit-db): add secondary indexes on audit_events, lifecycle_events, claim_citations (#312)
9bde940 fix(web-ui): auto-scroll content panel during agentic workflow progress (#308)
8b86f9f fix(v1.2): suppress pre_prompt after agentic workflow completion (#306)
84e692d fix(scheduler): drain subprocess pipes after kill on timeout and cancellation (#307)
92726ab docs: add agentic workflow video; replace inline links with 3-thumbnail gallery (#305)
ebaf839 fix(v1.2): display snapshot timestamps in local time format (#304)
63237d7 feat(v1.2): add get_page_states step to agentic reingest workflow (#303)
6b3531e test(live): exclude thin-content slug patterns from context-budget node picker (#301)
af0c718 feat: support run agentic workflow via query CLI command line (#300)
81e0935 fix(test): live tests update (#298)

Acknowledgements

Built and maintained by the Synthadoc team.

Assets 2
Loading