docs: site polish — How it works, Features, and Troubleshooting pages#123
Merged
Conversation
…ure diagram Move the overview "How it works" section onto its own docs page and replace the Mermaid block with a hand-authored SVG: solid arrows for synchronous flow, dotted for asynchronous, and rounded-orthogonal connectors for the SQLite-state and outcome-sync feedback loops. This restructure was pushed to the precision-lever branch after PR #119 was squash-merged, so it never reached main; re-applied here on the current release line.
mountainowl
changed the title
mountainowl
changed the title
mountainowl
added a commit
that referenced
this pull request
Jun 18, 2026
…im README (#125) Recovers the docs work stranded when PR #123 squash-merged at a stale head (a GitHub PR-head-sync glitch left only the first commit, the How it works page, in main). This carries the remaining changes on top of current main: - Features page (docs/features.md) + Highlighted-features rename and full-list link on the Overview. - Troubleshooting page (docs/troubleshooting.md); host/infra block trimmed out of operate.md. - Configuration reference restructured into per-[section] tables + example TOML, documents [mcp_server], adds a quick-start config; feature deep-dives preserved verbatim. - Self-hosted / in-house OpenAI-compatible model recipe (recipes.md). - Nav: Run/MCP/GitHub Action nested under Install and configure (navigation.indexes); Examples and References excluded from the site (source kept). - README slimmed to a git-level front door that defers to the docs site. Co-authored-by: mountainowl <mountainowl@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs-site restructuring & content + a README/docs split. Independent commits, each its own concern; docs-only, no application code touched.
Pages
how-it-works.md+images/architecture.svg) — walkthrough on its own page with a hand-authored sync/async architecture SVG. (Orphaned by feat(review): operator-configurable precision levers (category taxonomy, mode presets, calibrated confidence) #119's squash-merge; re-applied.)features.md) — plain-language, multi-audience overview; links to the relevant recipe/config/reference.troubleshooting.md, trimsoperate.md) — host/infra block pulled out and rewritten as terse symptom → cause → fix.Nav & site shape
4. Nested Run / MCP server / GitHub Action under Install and configure (
navigation.indexes).5. Examples hidden until it has screenshots (
exclude_docs, source kept).6. References dropped from the published site — maintainer notes, not user docs (
exclude_docs, source kept).Content
7. "Features at a glance" → "Highlighted features" (Overview + README); icons dropped; View full list of features link added.
8. Configuration reference restructured into a table + example TOML per
[section](incl. the previously-undocumented[mcp_server]) with a copy-paste quick-start config; six feature deep-dives preserved verbatim (anchors intact).9. New self-hosted / in-house OpenAI-compatible model recipe (
recipes.md).README / docs split
10.
README.mdslimmed 201 → 78 lines to a git-level front door — badges, one-paragraph what-it-is, install one-liner, compact docs-link table, Status, Security, Community. Marketing/how-to content now lives only on the docs site (the comprehensive, multi-audience documentation), linked from the README.Verification
mkdocs build --strict— clean; page links, cross-links, and nav nesting resolveconfiguration.md#…anchors verified in built HTML; deep-dive prose byte-identical via region diffcz check— all commits conform to Conventional Commits