codedebrief 0.11.0__tar.gz → 0.12.0__tar.gz

{codedebrief-0.11.0 → codedebrief-0.12.0}/CHANGELOG.md

@@ -6,6 +6,26 @@ The project follows Semantic Versioning.
 
 ## Unreleased
 
+## 0.12.0 - 2026-06-21
+
+### Added
+
+- Published the `codedebrief` package on PyPI and made `uv tool install codedebrief` the
+  primary README install path.
+- Added a README screenshot for the manual `codedebrief view` canvas.
+
+### Changed
+
+- Updated generated agent guidance so workflow artifacts are refreshed after
+  workflow-relevant changes before finalizing or committing.
+- Made CodeDebrief workflow visuals vertical by default, with horizontal output reserved
+  for explicit compact-overview requests.
+
+### Fixed
+
+- Fixed the manual viewer details rail so the Analysis Health panel no longer leaves a
+  stale empty source panel when no flow source is selected.
+
 ## 0.11.0 - 2026-06-21
 
 ### Added

{codedebrief-0.11.0 → codedebrief-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codedebrief
-Version: 0.11.0
+Version: 0.12.0
 Summary: Visual code workflow explorer for coding agents. Builds deterministic, source-grounded Mermaid flowcharts via MCP, local-first, with no API key.
 Project-URL: Homepage, https://github.com/ferdinandobons/CodeDebrief
 Project-URL: Documentation, https://github.com/ferdinandobons/CodeDebrief#readme
@@ -75,7 +75,7 @@ user explicitly asks for a compact overview.
 > Status: pre-1.0 alpha. The model is versioned, but schema and MCP payloads may evolve
 > before 1.0.
 >
-> Latest release: [v0.11.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.11.0)
+> Latest release: [v0.12.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.12.0)
 > · [Changelog](CHANGELOG.md)
 
 ## Why It Exists
@@ -103,7 +103,7 @@ uv tool install codedebrief
 To install a pinned GitHub release instead:
 
 ```bash
-uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.11.0"
+uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.12.0"
 ```
 
 Or install from a source checkout:
@@ -229,10 +229,14 @@ Mermaid visual returned by CodeDebrief:
    inspection; they are not the canonical chat visual.
 
 The model may choose the first visible depth, but the text inside shown blocks must come
-from CodeDebrief payloads. The answer should say that the diagram is a bounded summary and
-can be expanded. If the user wants a more language-friendly view, the agent may rewrite
-labels in the user's language as a separate presentation layer, preserving ids or source
-anchors and without adding facts.
+from CodeDebrief payloads. After the visual, the answer should include a short
+high-level written flow in the user's language, derived from ordered steps, selected
+flows, decisions, domain logic, and source ranges. That written flow should explain the
+happy path first and include only the branches needed by the request. The answer should
+also say that the diagram is a bounded summary and can be expanded. If the user wants a
+more language-friendly view, the agent may rewrite both labels and the written flow in
+the user's language as a separate presentation layer, preserving ids or source anchors
+and without adding facts.
 
 ## MCP Surface
 
@@ -276,6 +280,11 @@ codedebrief view
 codedebrief view --render-only --no-open
 ```
 
+![CodeDebrief manual viewer showing the interactive project flowchart](docs/assets/codedebrief-view-preview.png)
+
+Example manual view: the interactive browser canvas for exploring scopes, files, entry
+points, and connected workflow flows.
+
 Use the viewer when you need to inspect the whole project graph, navigate scopes, compare
 neighboring flows, or visually follow callers and callees. Use MCP when an agent should
 answer a bounded question with a focused `workflow_slice`.

{codedebrief-0.11.0 → codedebrief-0.12.0}/README.md

@@ -27,7 +27,7 @@ user explicitly asks for a compact overview.
 > Status: pre-1.0 alpha. The model is versioned, but schema and MCP payloads may evolve
 > before 1.0.
 >
-> Latest release: [v0.11.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.11.0)
+> Latest release: [v0.12.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.12.0)
 > · [Changelog](CHANGELOG.md)
 
 ## Why It Exists
@@ -55,7 +55,7 @@ uv tool install codedebrief
 To install a pinned GitHub release instead:
 
 ```bash
-uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.11.0"
+uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.12.0"
 ```
 
 Or install from a source checkout:
@@ -181,10 +181,14 @@ Mermaid visual returned by CodeDebrief:
    inspection; they are not the canonical chat visual.
 
 The model may choose the first visible depth, but the text inside shown blocks must come
-from CodeDebrief payloads. The answer should say that the diagram is a bounded summary and
-can be expanded. If the user wants a more language-friendly view, the agent may rewrite
-labels in the user's language as a separate presentation layer, preserving ids or source
-anchors and without adding facts.
+from CodeDebrief payloads. After the visual, the answer should include a short
+high-level written flow in the user's language, derived from ordered steps, selected
+flows, decisions, domain logic, and source ranges. That written flow should explain the
+happy path first and include only the branches needed by the request. The answer should
+also say that the diagram is a bounded summary and can be expanded. If the user wants a
+more language-friendly view, the agent may rewrite both labels and the written flow in
+the user's language as a separate presentation layer, preserving ids or source anchors
+and without adding facts.
 
 ## MCP Surface
 
@@ -228,6 +232,11 @@ codedebrief view
 codedebrief view --render-only --no-open
 ```
 
+![CodeDebrief manual viewer showing the interactive project flowchart](docs/assets/codedebrief-view-preview.png)
+
+Example manual view: the interactive browser canvas for exploring scopes, files, entry
+points, and connected workflow flows.
+
 Use the viewer when you need to inspect the whole project graph, navigate scopes, compare
 neighboring flows, or visually follow callers and callees. Use MCP when an agent should
 answer a bounded question with a focused `workflow_slice`.

{codedebrief-0.11.0 → codedebrief-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codedebrief"
-version = "0.11.0"
+version = "0.12.0"
 description = "Visual code workflow explorer for coding agents. Builds deterministic, source-grounded Mermaid flowcharts via MCP, local-first, with no API key."
 readme = "README.md"
 requires-python = ">=3.10"

{codedebrief-0.11.0 → codedebrief-0.12.0}/src/codedebrief/install.py

@@ -104,27 +104,33 @@ flusso, or similar code path:
 9. If neither exact canonical Mermaid nor a returned Mermaid artifact can be used, say
    that the deterministic visual cannot be shown in this client and provide `viewer_targets`;
    never create a replacement Mermaid diagram from prose or source reads.
-10. Say that the displayed diagram is a bounded summary of the selected logic and can be
-   expanded. If the user asks for a more language-friendly version, rewrite the technical
-   block labels in simple wording using the language of the user's request. Present that
-   as a human-friendly translation derived only from returned node, edge, decision, and
-   source fields.
-11. End with concise follow-up choices in the user's language: simplify the labels into
-   language-friendly wording, expand omitted nodes/branches/adjacent flows, or explore a
-   related area or deeper path.
-12. Also provide the `viewer_targets` command and hash
+10. After the visual, include a short "High-level flow" section in the user's language.
+   Derive it only from `ordered_steps`, primary/supporting flows, decisions,
+   domain logic, source ranges, and focused follow-up payloads. Keep it to a compact
+   happy-path walkthrough with only the branches needed by the question.
+11. Say that the displayed diagram is a bounded summary of the selected logic and can be
+   expanded.
+12. If the user asks for a more language-friendly version, rewrite both the technical
+   block labels and the high-level written flow in simple wording using the language of
+   the user's request. Present that as a human-friendly translation derived only from
+   returned node, edge, decision, step, and source fields.
+13. End with concise follow-up choices in the user's language: simplify the labels and
+   written flow into language-friendly wording, expand omitted nodes/branches/adjacent
+   flows, or explore a related area or deeper path.
+14. Also provide the `viewer_targets` command and hash
    target so the user can open the same visual in `codedebrief view`.
-13. Treat `workflow_slice.presentation` as supporting context for this request, not as the
+15. Treat `workflow_slice.presentation` as supporting context for this request, not as the
    primary output.
-14. Keep the textual summary short and secondary. Do not answer with raw JSON or YAML unless
+16. Keep the written flow short and secondary to the deterministic visual. Do not answer
+   with raw JSON or YAML unless
    the user explicitly asks for it.
 
 ## Guardrails
 
 - MCP is local-first and deterministic; do not ask for provider keys for the primary
   workflow.
-- Treat language-friendly labels as a presentation layer derived from deterministic
-  workflow facts.
+- Treat language-friendly labels and high-level written flows as presentation layers
+  derived from deterministic workflow facts.
 - Use CodeDebrief to explain modeled code logic, not to present possible defects.
 - Use `codedebrief view` only for the human manual UI.
 """
@@ -159,6 +165,10 @@ For codebase questions about behavior, decisions, workflow structure, or changed
    Inspect the full returned `workflow_slice` before deciding what to show. Choose the
    first visible depth yourself: show the clearest useful subset, then say that the
    displayed diagram is a bounded summary and can be expanded.
+   After the visual, include a short high-level written flow in the user's language,
+   derived only from returned ordered steps, primary/supporting flows, decisions, domain
+   logic, source ranges, and focused follow-up payloads. Keep it compact and explain the
+   happy path first, adding only the branches needed by the request.
    If the CodeDebrief result is too large, saved externally, truncated, or missing the exact
    canonical visual, retry with a smaller `token_budget` and narrower `flow_id`, `symbol`,
    `current_file`, or `scope`; do not recover by listing flows and hand-building a
@@ -169,12 +179,13 @@ For codebase questions about behavior, decisions, workflow structure, or changed
    explanation after the deterministic visual is shown and must not change displayed
    nodes, edges, labels, or branches. If neither exact canonical Mermaid nor a returned
    Mermaid artifact can be used, say so and provide `viewer_targets` instead of creating
-   a replacement Mermaid diagram. If the user asks for a more language-friendly version, rewrite the
-   technical block labels in simple wording using the language of the user's request. This
-   is allowed only as a separate presentation layer derived from returned node, edge,
-   decision, and source fields. End visual answers with concise options in the user's
-   language: simplify labels, expand omitted nodes/branches/adjacent flows, or explore a
-   related area. Show raw JSON or YAML only when explicitly requested.
+   a replacement Mermaid diagram. If the user asks for a more language-friendly version,
+   rewrite the technical block labels and the high-level written flow in simple wording
+   using the language of the user's request. This is allowed only as a separate
+   presentation layer derived from returned node, edge, decision, step, and source fields.
+   End visual answers with concise options in the user's language: simplify labels and
+   written flow, expand omitted nodes/branches/adjacent flows, or explore a related area.
+   Show raw JSON or YAML only when explicitly requested.
 4. Use `expand_slice`, `workflow_path`, `snapshot_slice`, `explain_flow`, `explain_node`,
    or `explain_edge` only when the first slice needs more precise context.
 5. Use `codedebrief view ...` only when a human wants the manual UI flowchart.
@@ -185,8 +196,9 @@ When helping a user set up or learn CodeDebrief:
    command you plan to run or recommend.
 2. Use `codedebrief doctor` when install, dependency, or parser capability issues are
    unclear.
-3. Do not ask for LLM provider keys for the primary workflow. Language-friendly labels
-   are a presentation layer derived from deterministic workflow facts.
+3. Do not ask for LLM provider keys for the primary workflow. Language-friendly labels and
+   high-level written flows are presentation layers derived from deterministic workflow
+   facts.
 4. `codedebrief setup-agent <target>` updates only that target's files. Run the command
    separately for each agent surface you want to configure, preserving any target-specific
    frontmatter and local notes.

{codedebrief-0.11.0 → codedebrief-0.12.0}/src/codedebrief/mcp_server.py

@@ -753,6 +753,17 @@ def _workflow_presentation_contract(
                 "label": "Canonical Visual",
                 "source_fields": ["presentation.canonical_visual"],
             },
+            {
+                "label": "High-Level Flow",
+                "source_fields": [
+                    "ordered_steps",
+                    "primary_flows",
+                    "supporting_flows",
+                    "decisions",
+                    "domain_logic",
+                    "source_ranges",
+                ],
+            },
             {"label": "Primary Flows", "source_fields": ["primary_flows"]},
             {"label": "Supporting Flows", "source_fields": ["supporting_flows"]},
             {"label": "Ordered Steps", "source_fields": ["ordered_steps"]},
@@ -767,11 +778,17 @@ def _workflow_presentation_contract(
             "this payload.",
             "Tell the user the shown diagram is a bounded summary of the selected "
             "logic and can be expanded.",
+            "After the visual, add a short high-level written flow in the user's "
+            "language. Derive it from ordered_steps, primary/supporting flows, "
+            "decisions, domain_logic, source_ranges, and focused follow-up tool "
+            "payloads; keep the happy path first and include only branches needed "
+            "by the request.",
             "End visual answers with concise follow-up choices: simplify labels in "
             "the user's language, expand omitted nodes or branches, or explore a "
             "related area.",
-            "A separate human-friendly translation may rewrite labels in the user's "
-            "language only from returned node, edge, source, and decision fields.",
+            "A separate human-friendly translation may rewrite labels and the "
+            "high-level written flow in the user's language only from returned "
+            "node, edge, source, step, and decision fields.",
             "Use ordered_steps as the canonical walkthrough and keep source anchors visible.",
             "Keep flow_id and node_id values visible so the slice can be expanded.",
             "Do not invent steps, constants, limits, error codes, or branches outside "
@@ -803,8 +820,29 @@ def _workflow_presentation_contract(
                 "but it must preserve all displayed facts exactly from the selected "
                 "workflow_slice or focused follow-up tool payloads."
             ),
+            "written_flow": {
+                "placement": "After the visual and before follow-up choices.",
+                "language": "Use the language of the user's request.",
+                "source_fields": [
+                    "ordered_steps",
+                    "primary_flows",
+                    "supporting_flows",
+                    "decisions",
+                    "domain_logic",
+                    "source_ranges",
+                ],
+                "style": (
+                    "Keep it compact, high-level, and source-grounded. Explain the "
+                    "happy path first, then only the branches needed by the user's "
+                    "question. Do not introduce facts absent from the payload."
+                ),
+                "language_friendly_rewrite": (
+                    "When simplifying diagram labels, rewrite this written flow with "
+                    "the same simplified wording and language."
+                ),
+            },
             "closing_options": [
-                "Offer a language-friendly rewrite of the graph labels in the user's language.",
+                "Offer a language-friendly rewrite of the graph labels and written flow.",
                 "Offer to expand the diagram with omitted nodes, branches, or adjacent flows.",
                 "Offer to explore another related area or deepen a specific path.",
             ],
@@ -817,8 +855,9 @@ def _workflow_presentation_contract(
             "human_friendly": (
                 "A human-friendly translation may replace technical labels with "
                 "clearer wording in the language used by the user, only as a separate "
-                "presentation layer. Preserve ids or source anchors and do not add "
-                "facts absent from the workflow_slice payload."
+                "presentation layer. Rewrite the high-level written flow with the "
+                "same simplified terminology. Preserve ids or source anchors and do "
+                "not add facts absent from the workflow_slice payload."
             ),
         },
         "media_policy": {
@@ -851,10 +890,12 @@ def _workflow_presentation_contract(
             "block as the primary visual unless the user asks for raw or copyable Mermaid. "
             "Do not render snapshot.svg inline by default; use SVG only when explicitly "
             "requested or for local inspection. Do not synthesize a new Mermaid diagram. "
-            "Explain that the diagram is a bounded summary and can be expanded. End with "
-            "options to simplify labels in the user's language, expand the graph with "
-            "omitted details, or explore a related area. Open viewer_targets with "
-            "codedebrief view for manual inspection."
+            "Explain that the diagram is a bounded summary and can be expanded. Add a "
+            "short high-level written flow in the user's language after the visual and "
+            "before follow-up options. End with options to simplify labels and the "
+            "written flow in the user's language, expand the graph with omitted details, "
+            "or explore a related area. Open viewer_targets with codedebrief view for "
+            "manual inspection."
         ),
         "canonical_visual": canonical_visual,
         "recommended_next_tools": {

{codedebrief-0.11.0 → codedebrief-0.12.0}/src/codedebrief/render/assets/panels.js

@@ -17,6 +17,7 @@
       const sourcePanel = document.getElementById("sourcePanel");
       const sourceBody = document.getElementById("source");
       const sourceFileEl = document.getElementById("sourceFile");
+      const rightRail = document.getElementById("rightRail");
       const qualityPanel = document.getElementById("qualityPanel");
       const qualityBody = document.getElementById("quality");
       const qualityCountEl = document.getElementById("qualityCount");
@@ -36,6 +37,11 @@
         if (node) node.replaceChildren();
       }
 
+      function setSourcePanelVisible(visible) {
+        if (sourcePanel) sourcePanel.hidden = !visible;
+        if (rightRail) rightRail.toggleAttribute("data-source-hidden", !visible);
+      }
+
       function metricValue(value) {
         if (value == null || value === "") return "0";
         if (typeof value === "number") return String(value);
@@ -265,7 +271,7 @@
         const flow = sourceFlowFor(sel || {});
         clear(sourceBody);
         if (sourceFileEl) sourceFileEl.textContent = "";
-        if (sourcePanel) sourcePanel.hidden = !flow;
+        setSourcePanelVisible(!!flow);
 
         if (!flow) {
           sourceBody.appendChild(el("p", "panel-empty", "Select a flow or node to view its source."));

{codedebrief-0.11.0 → codedebrief-0.12.0}/src/codedebrief/render/assets/styles.css

@@ -1274,6 +1274,11 @@
       overflow: hidden;
     }
     .panel-quality { flex: 0 0 auto; max-height: 260px; border-bottom: 1px solid var(--line); }
+    .right-rail[data-source-hidden] .panel-quality {
+      flex: 1 1 auto;
+      max-height: none;
+      border-bottom: 0;
+    }
     .panel-source { flex: 1 1 48%; border-bottom: 1px solid var(--line); }
     .panel[data-collapsed] {
       flex: 0 0 auto;

{codedebrief-0.11.0 → codedebrief-0.12.0}/tests/test_artifacts_query_install.py

@@ -63,9 +63,13 @@ def _assert_current_agent_instructions(content: str) -> None:
     assert "hand-building a\n   diagram" in content
     assert "bounded summary" in content
     assert "can be expanded" in content
+    assert "short high-level written flow" in content
+    assert "happy path first" in content
+    assert "only the branches needed by the request" in content
     assert "language-friendly" in content
+    assert "technical block labels and the high-level written flow" in content
     assert "language of the user's request" in content
-    assert "simplify labels" in content
+    assert "simplify labels and\n   written flow" in content
     assert "omitted nodes/branches/adjacent flows" in content
     assert "related area" in content
     assert "synthesize a new Mermaid" in content
@@ -123,10 +127,13 @@ def _assert_codedebrief_skill(content: str) -> None:
     assert "hand-building a diagram" in content
     assert "low-signal implementation node" in content
     assert "bounded summary" in content
+    assert 'short "High-level flow" section' in content
+    assert "compact\n   happy-path walkthrough" in content
     assert "human-friendly" in content
     assert "language-friendly" in content
-    assert "language of the user's request" in content
-    assert "simplify the labels" in content
+    assert "block labels and the high-level written flow" in content
+    assert "language of\n   the user's request" in content
+    assert "simplify the labels and\n   written flow" in content
     assert "expand omitted" in content
     assert "related area or deeper path" in content
     assert "synthesize a new Mermaid" in content
@@ -138,7 +145,7 @@ def _assert_codedebrief_skill(content: str) -> None:
     assert "workflow_slice.handle.flow_ids" in content
     assert "`viewer_targets` command" in content
     assert "`workflow_slice.presentation` as supporting context" in content
-    assert "Do not answer with raw JSON or YAML" in content
+    assert "Do not answer\n   with raw JSON or YAML" in content
     assert "POTENTIAL_GAP" not in content
 
 

{codedebrief-0.11.0 → codedebrief-0.12.0}/tests/test_cli.py

@@ -44,9 +44,13 @@ def _assert_current_agent_instructions(content: str) -> None:
     assert "hand-building a\n   diagram" in content
     assert "bounded summary" in content
     assert "can be expanded" in content
+    assert "short high-level written flow" in content
+    assert "happy path first" in content
+    assert "only the branches needed by the request" in content
     assert "language-friendly" in content
+    assert "technical block labels and the high-level written flow" in content
     assert "language of the user's request" in content
-    assert "simplify labels" in content
+    assert "simplify labels and\n   written flow" in content
     assert "omitted nodes/branches/adjacent flows" in content
     assert "related area" in content
     assert "synthesize a new Mermaid" in content
@@ -103,10 +107,13 @@ def _assert_codedebrief_skill(content: str) -> None:
     assert "hand-building a diagram" in content
     assert "low-signal implementation node" in content
     assert "bounded summary" in content
+    assert 'short "High-level flow" section' in content
+    assert "compact\n   happy-path walkthrough" in content
     assert "human-friendly" in content
     assert "language-friendly" in content
-    assert "language of the user's request" in content
-    assert "simplify the labels" in content
+    assert "block labels and the high-level written flow" in content
+    assert "language of\n   the user's request" in content
+    assert "simplify the labels and\n   written flow" in content
     assert "expand omitted" in content
     assert "related area or deeper path" in content
     assert "synthesize a new Mermaid" in content
@@ -117,7 +124,7 @@ def _assert_codedebrief_skill(content: str) -> None:
     assert "`workflow_slice` payload" in content
     assert "`viewer_targets` command" in content
     assert "`workflow_slice.presentation` as supporting context" in content
-    assert "Do not answer with raw JSON or YAML" in content
+    assert "Do not answer\n   with raw JSON or YAML" in content
 
 
 def test_top_level_help_prioritizes_flag_light_quickstart() -> None:

{codedebrief-0.11.0 → codedebrief-0.12.0}/tests/test_mcp.py

@@ -245,10 +245,19 @@ def test_workflow_slice_anchors_natural_query_to_one_primary_flow(tmp_path: Path
     assert "start-flow" in {flow["id"] for flow in workflow_slice["supporting_flows"]}
     assert workflow_slice["presentation"]["schema_version"] == "workflow_slice.presentation.v1"
     assert "bounded summary" in " ".join(workflow_slice["presentation"]["agent_guidance"])
+    assert "high-level written flow" in " ".join(workflow_slice["presentation"]["agent_guidance"])
+    assert "High-Level Flow" in {
+        section["label"] for section in workflow_slice["presentation"]["default_sections"]
+    }
+    written_flow_policy = workflow_slice["presentation"]["display_policy"]["written_flow"]
+    assert written_flow_policy["placement"] == "After the visual and before follow-up choices."
+    assert "ordered_steps" in written_flow_policy["source_fields"]
+    assert "same simplified wording" in written_flow_policy["language_friendly_rewrite"]
     assert "language-friendly rewrite" in " ".join(
         workflow_slice["presentation"]["display_policy"]["closing_options"]
     )
     assert "human-friendly" in workflow_slice["presentation"]["label_policy"]["human_friendly"]
+    assert "high-level written flow" in workflow_slice["presentation"]["visual_guidance"]
 
     canonical_visual = workflow_slice["presentation"]["canonical_visual"]
     assert canonical_visual["schema_version"] == "workflow_slice.canonical_visual.v1"

{codedebrief-0.11.0 → codedebrief-0.12.0}/tests/test_render_html.py

@@ -284,7 +284,10 @@ def test_render_html_wires_state_aware_viewer_controls(tmp_path: Path) -> None:
     # The Source panel is meaningful only when a file/flow is selected; scope/root views
     # keep the details rail focused on analysis health instead of placeholder source
     # content.
-    assert "sourcePanel.hidden = !flow" in html
+    assert "sourcePanel.hidden = !visible" in html
+    assert 'rightRail.toggleAttribute("data-source-hidden", !visible)' in html
+    assert ".right-rail[data-source-hidden] .panel-quality" in html
+    assert "max-height: none" in html
 
     # Analysis-health metrics are surfaced in the details rail from generated metadata,
     # giving large-codebase exploration a visible analyzer coverage and precision snapshot.