Changelog

What changed.

The latest releases. The complete history lives in the repository.

0.6.3

Found by running the README quick start, as a new user, on a small public FastAPI repo (testdrivenio/fastapi-crud-async). Before these fixes the first run could not be deployed.

Fixed

  • FastAPI router prefixes were lost in a src/ layout. Absolute imports were resolved only from the repo root, so from app.api import notes in src/app/main.py never reached src/app/api/notes.py and include_router(..., prefix="/notes") was dropped: routes were recorded as / and /{id}. The docs then cited the real /notes/... routes, the claim validator marked them ungrounded, and the page went invalid, which blocks deepdoc deploy. The resolver now also tries the importing file’s ancestor directories (repo root still wins; if two ancestors match, the import stays unresolved instead of guessed). The engine fingerprint changed, so existing projects replan once.
  • Source files with doc-like words in their names were treated as docs. Any name containing notes, history, readme, changelog or glossary (for example notes.py, order_history.py) was classified docs and lost code priority. The rule now applies only to prose files (.md, .mdx, .rst, .txt, .adoc).
  • DeepDoc documented itself. .deepdoc.yaml and the legacy .deepdoc_plan.json / .deepdoc_file_map.json were scanned as project files, producing a “Documentation Generation Configuration” page in the user’s docs. They are now always excluded.
  • Dead-end recovery messages. After a partial first run, deepdoc update said “run deepdoc generate first” and deepdoc deploy said “run deepdoc generate again”, while plain generate refuses over existing docs. Both now point to deepdoc generate --force.

Docs

  • README: the chatbot extra needs Python 3.10–3.14, or 3.10–3.13 on Intel Macs (onnxruntime wheel availability); corrected the clone URL and the Azure example’s output_dir.
  • Troubleshooting: Python 3.15 install failure, Hugging Face 429 on the first embedding-model download, and recovering from a partial run.

0.6.2

Fixed

  • generate crashed on an OpenAPI spec with empty values. A spec containing info: (or paths, responses, tags, … ) with nothing under it parses to None, and dict.get(key, default) returns that None, so spec_to_context_string raised AttributeError inside BucketGenerationEngine.__init__ and aborted the whole run. deepdoc/openapi.py now coerces non-mapping/non-list values, parse_openapi_spec rejects a spec that is not a mapping, and a spec that still cannot be rendered is skipped instead of killing generation.

0.6.1

Fixed

  • Misleading “litellm not installed” error. deepdoc/llm/client.py caught any ImportError raised while preparing litellm and always reported it as a missing package, even when litellm was installed but its own import chain failed for another reason (a broken sub-dependency, a mismatched venv). The error now includes the real underlying message instead of a generic one, so reinstalling litellm isn’t the only diagnostic step offered when it isn’t the actual cause.

0.6.0

Added

  • site.repo_url is auto-detected from the git origin remote when left empty, the same way the commit SHA already was. SSH-style remotes are normalised to https, and an explicit config value still wins.

  • UI strings are overridable via site.labels. Covers Fumadocs’ own strings (search, toc, lastUpdate, editOnGithub, nextPage, previousPage, chooseTheme, …) and DeepDoc’s callout headings (note, tip, warning, danger, info). An unrecognised label warns rather than being silently dropped. No language switcher is added — this is relabelling, not internationalisation.

  • Sidebar navigation is controllable via site.nav. Pin or reorder top-level sections (sections), hoist pages above them (pin), rename a page or section (rename), remove one from the sidebar while leaving it URL-reachable (hide), and add entries the planner never produced (extra) — either a hand-written Markdown page or an external link.

    • extra closes a real gap: a hand-written .md dropped into the output directory already rendered and was reachable by URL, but had no way into the sidebar. Generation now also reports pages in that state.
    • Everything is derived from the saved plan, so reordering a sidebar costs no LLM call and no repository scan — it applies on the next deepdoc serve.
    • An override naming a page that does not exist warns and is skipped; a stale entry can never break a build.
  • Site chrome is configurable via site.chrome. Sidebar (on/off, default open level, collapsible), table of contents (on/off, clerk/normal style, heading depth), breadcrumbs, previous/next page footer, edit-this-page, last-updated, theme switch, search toggle, the sidebar commit/date strip, and extra navbar links. A configured site.logo replaces the project name in the navbar, with an optional separate dark-mode logo swapped in CSS so it is correct on first paint.

  • Branding: palette presets, fonts, code theme, logo and favicon. site.theme.preset selects one of seven built-in palettes (neutral, black, vitepress, ocean, catppuccin, dusk, purple); site.theme.tokens overrides any individual Fumadocs design token in light or dark; site.theme.code_theme picks the Shiki theme; and the long-dead site.logo, site.logo_dark, site.favicon and site.repo_url keys now do something — assets are copied into the site’s public/ and the repo URL drives the edit-this-page link.

    • Fonts (site.theme.fonts) are opt-in: empty by default, so the site makes no external request unless a family is named. Every stack keeps a real system fallback.
    • The theme is composed into CSS in Python and injected per request, so it re-applies on deepdoc serve with no regeneration. Precedence is preset → brand → explicit token overrides.
  • A configurable site surface in .deepdoc.yaml. New optional site.theme, site.chrome, site.nav and site.labels blocks cover palette preset, raw design-token overrides, fonts, code theme, TOC/sidebar/breadcrumb/footer toggles, navbar links, nav ordering and UI labels. Every key is optional and empty means “built-in default”, so an existing config renders exactly as before. site.colors is unchanged and stays where it is.

    • Invalid values never fail a build: an unknown preset, a malformed hex, a bad TOC style or depth, a navbar link missing a URL, or an edit link with no repo_url each warn and fall back.
    • Fonts are opt-in — empty by default, so no external font request is made.
  • deepdoc config set now rejects unknown keys instead of silently creating and persisting them, with a “did you mean” suggestion. User-defined maps (site.labels, site.nav.rename, site.theme.tokens.*, endpoint_groups) still accept any key.

  • Search works again. The generated site rendered Fumadocs’ search UI but had no /api/search endpoint, so the box opened and could never return a result. The route was lost in the MkDocs migration — the old one used the MDX-era source adapter this template no longer has. Rebuilt on createSearchAPI reading the generated Markdown directly, exported as a static index so it works in a fully static site with no server at runtime. Indexed prose is capped per page, which keeps the browser download to ~680 KB for a 48-page repo instead of ~3 MB.

  • Mermaid diagrams follow the site theme and open full screen. The renderer hardcoded mermaid’s neutral theme, which is a light theme, so every diagram was unreadable in dark mode. The theme now tracks the live .dark class and diagrams re-render when the theme is toggled. Clicking a diagram opens it full screen with wheel zoom, drag to pan, +/-/0 shortcuts and Escape to close — previously a large diagram could only be scrolled horizontally, with no way to zoom.

  • deepdoc serve now re-applies .deepdoc.yaml before starting the dev server. Edit your config, run deepdoc serve, and the change is live — no regeneration, no LLM calls, no repository scan. The site config and scaffold are rebuilt from the saved .deepdoc/plan.json, and changed settings are reported on startup. deepdoc deploy does the same, so a deploy can no longer ship a UI that is stale relative to the config.

    • A missing or pre-v2 saved plan warns and serves the existing site rather than failing.
    • The resync runs before the npm check, so a dependency change in the refreshed package.json triggers a reinstall.

Fixed

  • deepdoc serve and deepdoc deploy no longer refuse when the site directory is missing. Both checked for <site_dir>/package.json before re-applying the config, so a fresh clone — where site directories are normally gitignored, leaving docs and a saved plan but no site — was told to run deepdoc generate and pay for a full regeneration to rebuild something the saved plan already describes. The resync now runs first and rebuilds the scaffold with no LLM call; the guard only fires when there is genuinely no plan to rebuild from.

  • Brand colours now actually apply to the generated site. The template targeted Fumadocs v14 CSS variables (--fd-*) while shipping v15, which renamed every colour token to --color-fd-* and changed their values to complete colours. 28 references were therefore dead in both directions: --fd-primary: var(--brand) set a variable nothing reads, so the configured colour never reached the sidebar, TOC, search or buttons; and 27 hsl(var(--fd-*)) reads were invalid at computed-value time, so table and <hr> borders vanished, inline code lost its background, and muted text was not muted. Renamed the tokens and stripped the now-wrong hsl() wrapper.

  • site.colors.light and site.colors.dark do something. Both were written into CSS variables that nothing consumed. light now drives the dark-mode primary (better contrast on a dark background) and dark drives the light-mode link hover.

  • Empty brand colours no longer emit invalid CSS. DEFAULT_CONFIG ships site.colors.* as "", so the key exists and .get(key, default) returned "" rather than the default — emitting the invalid declaration --brand: ;. Colour resolution is now a single validated owner (resolve_colors) that also rejects malformed hex with a warning.

  • Template fixes now reach already-generated sites. The builder skipped any template file that already existed, so only deepdoc.config.json and app/globals.css were ever refreshed — changes to the layouts, lib/*.ts or the chatbot never arrived on upgrade. The builder now owns every file in next_template/; user-added files, node_modules/, .next/, openapi/ and public/ are untouched.

  • Non-English pages no longer fail the length gate. Page word count used str.split(), which undercounts Chinese and Japanese by 5-10x and drove every such page below the < 100 words validity check — burning a quality retry and a full rewrite each. CJK and kana characters are now counted individually. English counts are unchanged.

  • Aligned two stale in-code config fallbacks with their shipped defaults: decompose_threshold (5 → 7) and consolidation_similarity_threshold (0.70 → 0.55). Unreachable in production since load_config always merges over DEFAULT_CONFIG; the defaults themselves are unchanged.

Removed

  • Config keys that were never implemented. Each had zero readers, so setting one did nothing:

    • github_pages.* — deploy is a static export to <site_dir>/out/; there is no gh-pages path
    • chatbot.answer.rate_limits.* and chatbot.embeddings.rate_limits.* — rate limiting is real but wired only for llm.rate_limits, so these never affected chatbot requests. llm.rate_limits is unchanged.
    • chatbot.vector_store.kind — FAISS is hardcoded
    • chatbot.retrieval.deep_research_chunk_chars / _top_k — orphans from an earlier retrieval shape
    • include_feature_pages — its two siblings are live; this one never was
    • compatibility.deprecated_version_warning.minimum_version / .upgrade_command — the check compares major versions in code and hardcodes its own remedy text

    Existing .deepdoc.yaml files are unaffected: the keys are ignored rather than rejected, and nothing reads them. They can be deleted by hand.

Changed

  • Brand colours are written only to deepdoc.config.json and injected into <head> at request time; they are no longer baked into app/globals.css. This removes a duplicate source of truth and means a colour change applies on deepdoc serve without regenerating any Markdown.
  • _ensure_node_modules reinstalls when package.json content changes, tracked via a node_modules/.deepdoc-pkg-sha stamp rather than mtime.

0.5.5

Added

  • Safe generated-output defaults and ownership-aware cleanup. New projects write generated Markdown to deepdoc-docs/ and the Next.js scaffold to deepdoc-site/. DeepDoc now classifies exact generated paths, refuses tracked or unmanaged output/site collisions before writing, and makes --clean remove only DeepDoc-owned artifacts rather than recursively deleting an entire configured directory.
  • One-run output overrides. deepdoc generate --docs PATH --site PATH selects safe repository-relative output roots for a single generation without mutating .deepdoc.yaml; explicit overrides still refuse authored or unmanaged collisions.
  • Evidence-safe authored documentation intake. Existing authored docs are classified before they enter evidence, while DeepDoc/DeepWiki exports, generated references, and built docs sites remain inventoried but cannot become factual generation context.
  • Universal repository evidence foundation. DeepDoc now carries a repository model, persistent SQLite symbol/index store, content-addressed source storage, explicit unsupported-language inventory, and 50K-file scale validation.
  • Java and Rust parser support. Java and Rust files receive structured symbol extraction; Java additionally has AST-backed call extraction.
  • Fail-closed runtime evidence. Python, JS/TS/Vue, PHP/Laravel, and Go runtime facts now require parser-backed API/binding proof, bounded dispatch identities, and product/document-role eligibility. Documentation examples, AI exports, generated references, and built sites cannot create runtime facts.
  • Evidence provenance and reader citations. Claim validity now directly controls page/ledger quality state; source citations are reader-visible, commit-pinned when a known GitHub commit is available, and safe around frontmatter and code fences.
  • Hierarchical site navigation. Parent-child pages render recursively and retain parent reachability after incremental cleanup.
  • Product regression and benchmark gates. Adversarial/framework benchmark coverage and a FastAPI-shaped output-safety product gate are included, with an optional shallow real-FastAPI smoke verifier.

Fixed

  • generate --clean could delete repository-owned documentation and site content. Output and site roots are now validated before generation, cleaning, deployment, and site building; configured site_dir is honored across the builder, OpenAPI staging, serve, deploy, and update paths.
  • Modified generated pages could still be removed by legacy frontmatter adoption. A changed hash in the ownership manifest now preserves the file, even if it still has DeepDoc provenance fields.
  • Output migration could leave a generate/update run bound to the old unsafe directory. Generate and update now rebind their output paths and manifests after safety migration.
  • Runtime examples could become production architecture facts. Runtime discovery now excludes all document roles before parser/runtime analysis, including when callers use the public runtime API without supplying precomputed roles.
  • Runtime proof boundaries could accept transitive mutation, stale Go scheduler, and closure-callback false positives. JS mutation effects propagate through proven invocations, Go scheduler links use receiver provenance identity, and Laravel schedule proof revokes by-reference callback bindings.

0.5.4

Added

  • Deterministic semantic refinement of planning-unit boundaries (Slice B). A file left in the fallback “core” unit by service-name grouping can now be conservatively adopted into the named unit it actually belongs to, using call-graph, topology-cluster, endpoint-bundle, and runtime-task affinity as independent signals against a fixed-weight/margin threshold. Files with an explicit file_services assignment or marked foundational (e.g. shared topology dependencies) never move, regardless of affinity score.
  • Bounded cross-unit boundary context in planning prompts. Each planning unit’s CLASSIFY prompt can now include a cross_unit_context section — bounded, path-free BoundaryStubs (slug/direction/aggregate counts/evidence kinds only) describing related cross-service work, recomputed fresh on every retry-split, so a unit can be aware of adjacent services without any remote file path or title ever entering its local prompt.

Fixed

  • Boundary-refinement evidence could leak a remote service’s file paths into a local unit’s prompt. EndpointBundle.evidence and RuntimeTask.producer_files kept their full unfiltered lists in make_sub_scan(), and flow labels were derived from arbitrary upstream FlowCandidate titles (sometimes a slugified file path) that no character-level sanitizer could reliably distinguish from a real identifier. Nested evidence lists are now trimmed to the unit’s own files, and BoundaryStub.flow_labels — along with its sanitizer — was removed outright; flow co-occurrence now only contributes to the aggregate “flow” evidence kind and its score.
  • A service literally named “core” could seize the fallback unclaimed-files slot and have its own anchored files redistributed away. The unclaimed group is now identified by a structural PlanningUnit.unclaimed flag (preserved across split children) instead of a slug comparison against "core". An unclaimed unit that refinement resolves down to zero files is now dropped instead of still being planned (which reserved a page budget and spent three real LLM calls on an empty sub-scan).
  • Flow-based affinity signals were always dead in production. Flow candidates were only ever built inside the global plan stage, which runs after every unit is already planned — so scan.flow_candidates was empty during refinement. Flow candidates are now built once in plan_docs() before boundary refinement runs.
  • Topology cluster co-membership could move a file on weak evidence. topology.py assigns any leftover file to its best-guess cluster, and ties are broken by picking the single biggest cluster with no correctness signal attached. Its affinity weight is now below the minimum acceptance threshold, so it can only corroborate another signal, never justify a move on its own.
  • The CLASSIFY prompt’s bounded cross-unit context could get starved by unbounded optional sections filling the budget first. fit_prompt_sections fills optional sections greedily in list order; cross_unit_context is now ordered first among them, since (unlike the other, in-principle-unbounded sections) it’s the one section with a fixed small cap.
  • Unit membership changes now bump ENGINE_FINGERPRINT, forcing a full replan instead of reusing a plan/ledger computed under the old core-file assignment.
  • Redundant call-graph serialization. CallGraph.serialize() re-materialized a full edge/relation dict once per unit, per coarse unit, and per retry-split against the same scan. local_call_edges is now derived once in plan_docs() and threaded through instead.
Full changelog on GitHub