feat: use modal storytelling mode

README.md

@@ -56,7 +56,7 @@ The app lets a user paste:
 Then the user can choose:
 
 - Output language: Indonesian (`id`) or English (`en`)
-- Tone
+- Tone, when Modal storytelling mode is not enabled
 - Target audience
 - Whether to include frontmatter
 - Whether to include code snippets
@@ -79,6 +79,13 @@ Transcript extraction has two paths:
 - Deterministic local extraction for Claude Code/Codex-style tool logs.
 - Optional Modal vLLM extraction when `MODAL_VLLM_BASE_URL` is configured.
 
+Editorial polishing also has two paths:
+
+- Lightweight local quality scoring and deterministic cleanup.
+- Optional Modal vLLM rewrite when `MODAL_POLISH_ENABLED=true` and `MODAL_VLLM_BASE_URL` is configured.
+
+When Modal polishing is enabled, Vibe2Blog automatically uses a human storytelling editorial mode and ignores tone presets. Tone presets remain available only for deterministic fallback mode.
+
 ## Hackathon Fit
 
 Vibe2Blog is planned as a Gradio app hosted on Hugging Face Spaces.
@@ -226,13 +233,30 @@ Without `HF_TOKEN` and `VIBE2BLOG_MODEL`, the app uses a deterministic template
 Optional Modal transcript extraction:
 
 ```bash
-export MODAL_VLLM_BASE_URL="https://your-workspace--your-app-serve.modal.run"
+export MODAL_VLLM_BASE_URL="https://<workspace>--vibe2blog-backend-serve.modal.run/v1"
 export MODAL_VLLM_MODEL="llm"
+export MODAL_VLLM_TIMEOUT="45"
 .venv/bin/python app.py
 ```
 
 The Modal endpoint should expose an OpenAI-compatible `/v1/chat/completions` route, such as the vLLM server pattern from Modal's official example.
 
+Optional Modal editorial polishing:
+
+```bash
+export MODAL_VLLM_BASE_URL="https://<workspace>--vibe2blog-backend-serve.modal.run/v1"
+export MODAL_VLLM_MODEL="llm"
+export MODAL_POLISH_ENABLED="true"
+export MODAL_POLISH_TIMEOUT="60"
+.venv/bin/python app.py
+```
+
+When enabled, Vibe2Blog sends the generated Markdown draft to the Modal vLLM endpoint for a final editorial pass. The prompt instructs the model to preserve factual claims, YAML frontmatter, Markdown headings, file names, commands, verification results, and code blocks while improving flow, specificity, and readability. If Modal fails, the original draft is kept.
+
+Modal may return an initial `303` redirect for web server calls. Vibe2Blog follows that redirect while preserving the original POST body.
+
+In Modal storytelling mode, the UI hides tone presets and the model receives one editorial direction: write a natural technical story from the supplied context. Light transitions and connective sentences are allowed, but the model is instructed not to invent facts, files, tests, APIs, decisions, or outcomes.
+
 When implementing:
 
 - Keep the first screen as the working generator.

app.py

@@ -2,31 +2,46 @@ from __future__ import annotations
 
 import gradio as gr
 
+from vibe2blog.modal_polisher import should_polish_with_modal
 from vibe2blog.pipeline import generate_article
 
 
-SAMPLE_SUMMARY = """We planned Vibe2Blog, a Gradio app for the Build Small Hackathon.
-The product changed from CLI-first to Gradio-first so judges can try it directly in a Hugging Face Space.
-Important decisions:
-- Gradio is the hackathon MVP.
-- CLI and slash commands are future extensions.
-- Output supports Indonesian and English.
-- Likely secrets are redacted before generation.
-- The generated result is Markdown with frontmatter.
+MODAL_STORYTELLING_ENABLED = should_polish_with_modal()
+
+SAMPLE_TITLE = "Fixing a Login Button That Stayed Disabled"
+
+SAMPLE_SUMMARY = """> The login button stays disabled even after users enter a valid email and password.
+
+⏺ I'll inspect the login form state and validation logic.
+⏺ Read(src/screens/LoginScreen.tsx)
+⎿ Read 120 lines
+⏺ I found the issue. The form validates email and password correctly, but the disabled state reads from an old `isValid` flag that is never updated after typing.
+⏺ Search(pattern: "isValid", path: "src/screens")
+⎿ Found 3 matches
+⏺ Update(src/screens/LoginScreen.tsx)
+⎿ Updated src/screens/LoginScreen.tsx with 4 additions and 2 removals
+
+The fix removes the stale `isValid` state and derives `canSubmit` directly from the current email, password, loading state, and validation errors.
+
+> It works now. The button enables after valid input and disables while the login request is running.
 """
 
-SAMPLE_TRANSCRIPT = """The key product decision was to keep the core generator reusable while making the hackathon demo Gradio-first.
-We also added a Codex Track plan, GitHub-to-Hugging Face sync plan, and post-MVP extension PRDs for WordPress and Modal featured images.
+SAMPLE_TRANSCRIPT = """The session focused on a common UI bug: the visual form looked valid, but the submit button stayed disabled.
+The useful debugging step was comparing what the UI displayed with which state variable actually controlled the button.
 """
 
-SAMPLE_DIFF = """diff --git a/README.md b/README.md
-+ Added OpenAI Codex Track requirements.
-+ Added Hugging Face Space deployment plan.
-+ Added editorial quality pass to the roadmap.
+SAMPLE_DIFF = """diff --git a/src/screens/LoginScreen.tsx b/src/screens/LoginScreen.tsx
+- const [isValid, setIsValid] = useState(false)
+- const disabled = !isValid || isLoading
++ const canSubmit = emailError === "" && passwordError === "" && email !== "" && password !== ""
++ const disabled = !canSubmit || isLoading
 """
 
-SAMPLE_VERIFICATION = """Documentation baseline was committed with a Codex co-author trailer.
-The repo now includes PRDs, AGENTS.md, and Space deployment planning.
+SAMPLE_VERIFICATION = """Manual test:
+- Empty form keeps the login button disabled.
+- Invalid email keeps the button disabled and shows an error.
+- Valid email and password enable the button.
+- Clicking login disables the button while the request is pending.
 """
 
 
@@ -81,13 +96,13 @@ def generate(
 
 def load_sample() -> tuple[str, str, str, str, str, str, str, str, bool, bool, bool]:
     return (
-        "Mengubah Sesi Vibe Coding Menjadi Catatan Lapangan",
+        SAMPLE_TITLE,
         SAMPLE_SUMMARY,
         SAMPLE_TRANSCRIPT,
         SAMPLE_DIFF,
         SAMPLE_VERIFICATION,
-        "id",
-        "reflective",
+        "en",
+        "narrative",
         "developers",
         True,
         True,
@@ -121,11 +136,17 @@ with gr.Blocks(
 
     with gr.Row():
         with gr.Column(scale=5):
-            topic = gr.Textbox(label="Topic or working title", placeholder="Building Vibe2Blog for the Build Small Hackathon")
+            topic = gr.Textbox(
+                label="Topic or working title",
+                placeholder="Example: Fixing a Login Button That Stayed Disabled",
+            )
             session_summary = gr.Textbox(
                 label="Session summary or raw agent transcript",
                 lines=8,
-                placeholder="Paste a short summary or raw Claude Code/Codex-style session transcript...",
+                placeholder=(
+                    "Paste a summary or raw agent transcript. Example: the problem, what the agent inspected, "
+                    "what changed, how it was verified, and the final outcome."
+                ),
             )
             with gr.Accordion("Optional context", open=False):
                 transcript_excerpt = gr.Textbox(label="Transcript excerpt", lines=5)
@@ -136,7 +157,16 @@ with gr.Blocks(
             tone = gr.Dropdown(
                 ["reflective", "tutorial", "concise", "narrative"],
                 value="reflective",
-                label="Tone",
+                label="Tone (fallback mode only)",
+                visible=not MODAL_STORYTELLING_ENABLED,
+            )
+            gr.Markdown(
+                (
+                    "Modal storytelling mode is active. Tone presets are disabled so the model can shape a more natural engineering story from the supplied context."
+                    if MODAL_STORYTELLING_ENABLED
+                    else "Tone presets are used by the deterministic fallback when Modal storytelling mode is not enabled."
+                ),
+                elem_classes=["vibe2blog-note"],
             )
             audience = gr.Dropdown(
                 ["developers", "beginners", "maintainers", "product stakeholders"],
@@ -146,7 +176,7 @@ with gr.Blocks(
             include_code_snippets = gr.Checkbox(value=True, label="Include selected code snippets")
             include_frontmatter = gr.Checkbox(value=True, label="Include YAML frontmatter")
             editorial_quality_pass = gr.Checkbox(value=True, label="Editorial quality pass")
-            sample_button = gr.Button("Load sample data", variant="secondary")
+            sample_button = gr.Button("Load demo template", variant="secondary")
             generate_button = gr.Button("Generate Markdown", variant="primary")
             gr.Markdown(
                 "Do not paste secrets. Vibe2Blog redacts common token patterns and can summarize raw agent transcripts before building the prompt.",

docs/hackathon-submission-plan.md

@@ -65,11 +65,12 @@ Build a Hugging Face Space with a Gradio app that supports:
 - Optional git diff input.
 - Optional verification notes input.
 - Language selection: Indonesian (`id`) and English (`en`).
-- Tone selection.
+- Tone selection for fallback mode; Modal-backed storytelling mode should hide or ignore tone presets.
 - Audience selection.
 - Secret redaction before prompt construction.
 - Markdown generation with YAML frontmatter.
 - Editorial quality pass to reduce generic AI prose and improve specificity.
+- Optional Modal-backed editorial polishing for more natural Markdown drafts.
 - Markdown preview/editor.
 - Copy or download `.md`.
 - Built-in sample data for judges.
@@ -121,6 +122,10 @@ The implementation should keep the model behind an `ArticleGenerator` boundary s
 
 Transcript extraction can optionally use Modal credits through an OpenAI-compatible vLLM service. The Space should read `MODAL_VLLM_BASE_URL` and `MODAL_VLLM_MODEL`; if unavailable or failing, it must fall back to deterministic local extraction so the demo remains usable.
 
+Editorial polishing can use the same Modal endpoint when `MODAL_POLISH_ENABLED=true`. This should run after article generation and before validation/export. If Modal fails, the original draft should remain valid and downloadable.
+
+When Modal-backed polishing is enabled, the demo should emphasize natural storytelling over visible tone presets. The model may add light connective prose, but it must stay inside the provided coding-session context.
+
 Candidate model families to evaluate:
 
 - OpenBMB MiniCPM family for lightweight text/multimodal options.

docs/prd-blog-from-vibe-coding.md

@@ -75,6 +75,7 @@ Produk utama untuk hackathon adalah Gradio app yang di-host sebagai Hugging Face
 - The app will support `id` and `en` as first-class initial output languages.
 - The language option will control article prose, section headings, generated title, generated description, and language-related frontmatter.
 - The app will expose tone and audience controls as simple dropdowns.
+- Tone presets apply to deterministic fallback generation. When Modal-backed storytelling polish is enabled, tone presets are ignored so the model can shape a more natural technical story.
 - The app will produce Markdown with YAML frontmatter by default.
 - The default generated structure will include title, date, tags, introduction, problem context, implementation story, key technical decisions, verification, lessons learned, and conclusion.
 - The model used for the hackathon must fit the Build Small constraint of less than or equal to 32B parameters.
@@ -93,6 +94,10 @@ Produk utama untuk hackathon adalah Gradio app yang di-host sebagai Hugging Face
 - An `EditorialQualityPass` module will evaluate and optionally rewrite the draft for specificity, narrative flow, concrete technical detail, natural transitions, and reduced generic AI phrasing.
 - A `MarkdownExporter` module will produce downloadable Markdown bytes and a deterministic filename.
 - The MVP will use prompting, few-shot examples, style guidance, and rewrite passes for humanized writing quality.
+- The editorial rewrite pass may use a Modal-hosted OpenAI-compatible vLLM endpoint when `MODAL_POLISH_ENABLED=true` and `MODAL_VLLM_BASE_URL` is configured.
+- Modal polishing must preserve factual claims, Markdown structure, YAML frontmatter, code blocks, file names, commands, and verification results.
+- Modal polishing may add light transitions and connective sentences as long as they stay within the supplied context.
+- If Modal polishing fails, the app must keep the original generated draft rather than failing the user flow.
 - Fine-tuning is not required for the hackathon MVP.
 - Fine-tuning may be considered later if the project accumulates enough high-quality example articles and needs a consistent personal/editorial voice.
 - CLI and slash-command support are future extensions. They should reuse the same core modules after the Gradio MVP works.

requirements.txt

@@ -1,3 +1,3 @@
 gradio>=5.0,<6
 huggingface_hub>=0.23
-
+certifi>=2024.0.0

tests/test_generator_tones.py

@@ -78,6 +78,20 @@ class ToneTemplateTest(unittest.TestCase):
         self.assertNotIn("token", markdown)
         self.assertNotIn("role", markdown)
 
+    def test_storytelling_internal_tone_uses_narrative_seed_structure(self) -> None:
+        result = generate_article(
+            topic="Fixing a Login Button That Stayed Disabled",
+            session_summary="The login button used stale validity state and stayed disabled after valid input.",
+            language="en",
+            tone="human storytelling technical blog",
+            include_frontmatter=False,
+        )
+        markdown = result.generation.markdown
+
+        self.assertIn("## Opening", markdown)
+        self.assertIn("## Finding the Root Cause", markdown)
+        self.assertNotIn("## Goal", markdown)
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_modal_extractor.py

@@ -2,11 +2,14 @@ from __future__ import annotations
 
 import json
 import unittest
+import urllib.error
+from unittest.mock import MagicMock, patch
 
 from vibe2blog.modal_extractor import (
     build_chat_completions_url,
     build_system_prompt,
     parse_chat_completion_content,
+    post_json_with_modal_redirect,
 )
 
 
@@ -33,6 +36,36 @@ class ModalExtractorTest(unittest.TestCase):
 
         self.assertEqual(parse_chat_completion_content(body), "Initial problem: fixed")
 
+    def test_post_json_preserves_post_body_across_modal_303_redirect(self) -> None:
+        redirect = urllib.error.HTTPError(
+            "https://example.modal.run/v1/chat/completions",
+            303,
+            "See Other",
+            {"Location": "https://example.modal.run/call-id/v1/chat/completions"},
+            None,
+        )
+        final = MagicMock()
+        final.__enter__.return_value.read.return_value = b'{"ok": true}'
+        final.__exit__.return_value = False
+        opener = MagicMock()
+        opener.open.side_effect = [redirect, final]
+
+        with patch("vibe2blog.modal_extractor.urllib.request.build_opener", return_value=opener):
+            body = post_json_with_modal_redirect(
+                "https://example.modal.run/v1/chat/completions",
+                {"model": "llm"},
+                {"Content-Type": "application/json"},
+                timeout=10,
+            )
+
+        self.assertEqual(body, '{"ok": true}')
+        first_request = opener.open.call_args_list[0].args[0]
+        second_request = opener.open.call_args_list[1].args[0]
+        self.assertEqual(first_request.get_method(), "POST")
+        self.assertEqual(second_request.get_method(), "POST")
+        self.assertEqual(first_request.data, second_request.data)
+        self.assertEqual(second_request.full_url, "https://example.modal.run/call-id/v1/chat/completions")
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_modal_polisher.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import os
+import unittest
+from unittest.mock import patch
+
+from vibe2blog.context import normalize_context
+from vibe2blog.modal_polisher import (
+    STORYTELLING_TONE,
+    build_polish_system_prompt,
+    build_polish_user_prompt,
+    maybe_polish_markdown,
+    modal_polish_enabled,
+    polish_markdown_with_modal,
+    should_polish_with_modal,
+)
+
+
+class ModalPolisherTest(unittest.TestCase):
+    def test_modal_polish_is_disabled_by_default(self) -> None:
+        with patch.dict(os.environ, {}, clear=True):
+            self.assertFalse(modal_polish_enabled())
+            self.assertFalse(should_polish_with_modal())
+
+    def test_modal_polish_requires_flag_and_base_url(self) -> None:
+        with patch.dict(
+            os.environ,
+            {
+                "MODAL_POLISH_ENABLED": "true",
+                "MODAL_VLLM_BASE_URL": "https://example.modal.run",
+            },
+            clear=True,
+        ):
+            self.assertTrue(modal_polish_enabled())
+            self.assertTrue(should_polish_with_modal())
+
+    def test_indonesian_prompt_preserves_facts_and_markdown(self) -> None:
+        prompt = build_polish_system_prompt("id")
+
+        self.assertIn("Pertahankan semua klaim faktual", prompt)
+        self.assertIn("YAML frontmatter", prompt)
+        self.assertIn("code block", prompt)
+        self.assertIn("Jangan membuat YAML frontmatter", prompt)
+        self.assertIn("Jangan mengarang", prompt)
+        self.assertIn("Jangan memberi contoh", prompt)
+        self.assertIn("cerita teknis", prompt)
+        self.assertIn("kalimat penghubung ringan", prompt)
+
+    def test_user_prompt_includes_style_context(self) -> None:
+        context = normalize_context(
+            session_summary="We fixed a bug.",
+            language="en",
+            tone=STORYTELLING_TONE,
+            audience="maintainers",
+        )
+
+        prompt = build_polish_user_prompt("## Draft", context)
+
+        self.assertIn("Language: en", prompt)
+        self.assertIn(f"Editorial mode: {STORYTELLING_TONE}", prompt)
+        self.assertIn("Audience: maintainers", prompt)
+        self.assertIn("Return the edited version of this exact draft only.", prompt)
+        self.assertIn("## Draft", prompt)
+
+    def test_polish_markdown_calls_openai_compatible_endpoint(self) -> None:
+        context = normalize_context(session_summary="We fixed a bug.", language="en")
+        response_body = (
+            '{"choices":[{"message":{"content":"---\\ntitle: \\"Draft\\"\\n---'
+            '\\n\\n## Problem\\nPolished draft."}}]}'
+        )
+
+        with patch.dict(
+            os.environ,
+            {
+                "MODAL_VLLM_BASE_URL": "https://example.modal.run",
+                "MODAL_VLLM_MODEL": "llm",
+                "MODAL_POLISH_TIMEOUT": "12",
+            },
+            clear=True,
+        ):
+            with patch("vibe2blog.modal_polisher.post_json_with_modal_redirect", return_value=response_body) as post:
+                polished = polish_markdown_with_modal("## Problem\nDraft.", context)
+
+        self.assertIn("Polished draft", polished)
+        endpoint, payload, headers = post.call_args.args
+        self.assertEqual(endpoint, "https://example.modal.run/v1/chat/completions")
+        self.assertEqual(payload["model"], "llm")
+        self.assertEqual(payload["temperature"], 0.35)
+        self.assertEqual(headers["Content-Type"], "application/json")
+
+    def test_maybe_polish_falls_back_to_original_when_modal_fails(self) -> None:
+        context = normalize_context(session_summary="We fixed a bug.", language="en")
+        original = "## Problem\nOriginal draft."
+
+        with patch.dict(
+            os.environ,
+            {
+                "MODAL_POLISH_ENABLED": "true",
+                "MODAL_VLLM_BASE_URL": "https://example.modal.run",
+            },
+            clear=True,
+        ):
+            with patch("vibe2blog.modal_polisher.polish_markdown_with_modal", return_value=""):
+                self.assertEqual(maybe_polish_markdown(original, context), original)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_pipeline.py

@@ -2,10 +2,46 @@ from __future__ import annotations
 
 import tempfile
 import unittest
+from unittest.mock import patch
 
+from vibe2blog.context import SessionContext
+from vibe2blog.generator import ArticleGenerator, GenerationResult
+from vibe2blog.modal_polisher import STORYTELLING_TONE
 from vibe2blog.pipeline import generate_article
 
 
+class CapturingGenerator(ArticleGenerator):
+    markdown = """---
+title: "Captured"
+---
+
+## Problem
+Draft.
+
+## Context
+Context.
+
+## Change
+Change.
+
+## Verification
+Verification.
+"""
+
+    def __init__(self) -> None:
+        self.context: SessionContext | None = None
+
+    def generate(self, context: SessionContext) -> GenerationResult:
+        self.context = context
+        return GenerationResult(
+            markdown=self.markdown,
+            title="Captured",
+            quality_notes="Captured.",
+            prompt="",
+            provider="capturing",
+        )
+
+
 class ArticlePipelineTest(unittest.TestCase):
     def test_pipeline_generates_downloadable_markdown(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
@@ -46,6 +82,55 @@ class ArticlePipelineTest(unittest.TestCase):
         self.assertNotIn("⏺", markdown)
         self.assertTrue(result.validation.valid)
 
+    def test_pipeline_applies_modal_polish_when_configured(self) -> None:
+        polished = """---
+title: "Vibe2Blog"
+---
+
+## Problem
+Polished draft.
+
+## Context
+Specific context.
+
+## Change
+Specific change.
+
+## Verification
+Specific verification.
+"""
+
+        with patch("vibe2blog.pipeline.should_polish_with_modal", return_value=True):
+            with patch("vibe2blog.pipeline.maybe_polish_markdown", return_value=polished):
+                result = generate_article(
+                    topic="Vibe2Blog",
+                    session_summary="We built a Gradio app for turning coding sessions into Markdown.",
+                    language="en",
+                )
+
+        self.assertIn("Polished draft", result.generation.markdown)
+        self.assertIn("+modal-polish", result.generation.provider)
+        self.assertIn("Modal polish applied.", result.generation.quality_notes)
+        self.assertTrue(result.validation.valid)
+
+    def test_modal_storytelling_ignores_user_tone_before_generation(self) -> None:
+        generator = CapturingGenerator()
+
+        with patch("vibe2blog.pipeline.should_polish_with_modal", return_value=True):
+            with patch("vibe2blog.pipeline.maybe_polish_markdown", return_value=CapturingGenerator.markdown):
+                result = generate_article(
+                    generator=generator,
+                    topic="Fix login button",
+                    session_summary="The user selected tutorial, but Modal should own the editorial style.",
+                    language="en",
+                    tone="tutorial",
+                )
+
+        self.assertIsNotNone(generator.context)
+        self.assertEqual(generator.context.tone, STORYTELLING_TONE)
+        self.assertNotIn("+modal-polish", result.generation.provider)
+        self.assertTrue(result.validation.valid)
+
 
 if __name__ == "__main__":
     unittest.main()

vibe2blog/generator.py

@@ -117,14 +117,14 @@ def build_template_article(context: SessionContext) -> str:
             return build_indonesian_tutorial_template(context, title)
         if tone == "concise":
             return build_indonesian_concise_template(context, title)
-        if tone == "narrative":
+        if tone == "narrative" or "storytelling" in tone:
             return build_indonesian_narrative_template(context, title)
         return build_indonesian_reflective_template(context, title)
     if tone == "tutorial":
         return build_english_tutorial_template(context, title)
     if tone == "concise":
         return build_english_concise_template(context, title)
-    if tone == "narrative":
+    if tone == "narrative" or "storytelling" in tone:
         return build_english_narrative_template(context, title)
     return build_english_reflective_template(context, title)
 

vibe2blog/modal_extractor.py

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 import json
 import os
+import ssl
 import urllib.error
+import urllib.parse
 import urllib.request
 
 
@@ -48,21 +50,61 @@ def summarize_with_modal_vllm(raw_text: str, *, language: str) -> str:
     if api_key:
         headers["Authorization"] = f"Bearer {api_key}"
 
-    request = urllib.request.Request(
-        endpoint,
-        data=json.dumps(payload).encode("utf-8"),
-        headers=headers,
-        method="POST",
-    )
     try:
-        with urllib.request.urlopen(request, timeout=timeout) as response:
-            body = response.read().decode("utf-8")
+        body = post_json_with_modal_redirect(endpoint, payload, headers, timeout=timeout)
     except (OSError, urllib.error.HTTPError, urllib.error.URLError):
         return ""
 
     return parse_chat_completion_content(body)
 
 
+class NoPostRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Expose Modal redirects so callers can repeat POST with the same body."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+def post_json_with_modal_redirect(
+    endpoint: str,
+    payload: dict,
+    headers: dict[str, str],
+    *,
+    timeout: float,
+    max_redirects: int = 3,
+) -> str:
+    """POST JSON and manually follow Modal 303 redirects without changing to GET."""
+    data = json.dumps(payload).encode("utf-8")
+    opener = build_modal_opener()
+    url = endpoint
+    for _ in range(max_redirects + 1):
+        request = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        try:
+            with opener.open(request, timeout=timeout) as response:
+                return response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            if exc.code not in {301, 302, 303, 307, 308}:
+                raise
+            location = exc.headers.get("Location")
+            if not location:
+                raise
+            url = urllib.parse.urljoin(url, location)
+    return ""
+
+
+def build_modal_opener() -> urllib.request.OpenerDirector:
+    """Build an opener that understands Modal redirects and local CA bundles."""
+    handlers: list[object] = [NoPostRedirectHandler]
+    try:
+        import certifi
+    except ImportError:
+        pass
+    else:
+        context = ssl.create_default_context(cafile=certifi.where())
+        handlers.append(urllib.request.HTTPSHandler(context=context))
+    return urllib.request.build_opener(*handlers)
+
+
 def build_chat_completions_url(base_url: str) -> str:
     """Normalize a Modal web server URL into the OpenAI chat completions route."""
     trimmed = base_url.rstrip("/")

vibe2blog/modal_polisher.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import os
+import urllib.error
+
+from .context import SessionContext
+from .modal_extractor import (
+    DEFAULT_MODAL_MODEL,
+    build_chat_completions_url,
+    parse_chat_completion_content,
+    post_json_with_modal_redirect,
+)
+
+
+STORYTELLING_TONE = "human storytelling technical blog"
+
+
+def modal_polish_enabled() -> bool:
+    """Enable the polish pass only when the user explicitly opts in."""
+    enabled = os.getenv("MODAL_POLISH_ENABLED", "false").strip().lower()
+    return enabled in {"1", "true", "yes", "on"}
+
+
+def should_polish_with_modal() -> bool:
+    """Check both the feature flag and the shared Modal vLLM endpoint config."""
+    return modal_polish_enabled() and bool(os.getenv("MODAL_VLLM_BASE_URL", "").strip())
+
+
+def polish_markdown_with_modal(markdown: str, context: SessionContext) -> str:
+    """Rewrite a Markdown draft through Modal vLLM, returning blank on failure."""
+    base_url = os.getenv("MODAL_VLLM_BASE_URL", "").strip()
+    if not base_url:
+        return ""
+
+    model = os.getenv("MODAL_VLLM_MODEL", DEFAULT_MODAL_MODEL).strip() or DEFAULT_MODAL_MODEL
+    timeout = float(os.getenv("MODAL_POLISH_TIMEOUT", "60"))
+    endpoint = build_chat_completions_url(base_url)
+    payload = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": build_polish_system_prompt(context.language)},
+            {"role": "user", "content": build_polish_user_prompt(markdown, context)},
+        ],
+        "temperature": 0.35,
+        "top_p": 0.9,
+        "max_tokens": 1800,
+    }
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    api_key = os.getenv("MODAL_VLLM_API_KEY", "").strip()
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    try:
+        body = post_json_with_modal_redirect(endpoint, payload, headers, timeout=timeout)
+    except (OSError, urllib.error.HTTPError, urllib.error.URLError):
+        return ""
+
+    return parse_chat_completion_content(body)
+
+
+def build_polish_system_prompt(language: str) -> str:
+    """Constrain Modal to editorial polish, not new article generation."""
+    if language == "id":
+        return (
+            "Kamu adalah editor teknis untuk Vibe2Blog. "
+            "Poles draft Markdown agar terasa lebih natural, spesifik, dan manusiawi. "
+            "Pertahankan semua klaim faktual, struktur Markdown, YAML frontmatter, heading, "
+            "nama file, command, hasil verifikasi, dan code block. "
+            "Jangan membuat YAML frontmatter, tanggal, author, tag, atau metadata baru jika tidak ada di draft. "
+            "Jangan mengarang test, file, API, keputusan, hasil, atau detail baru. "
+            "Hilangkan frasa AI generik dan perbaiki alur transisi. "
+            "Susun ulang draft sebagai cerita teknis yang enak diikuti: masalah, penelusuran, momen temuan, perubahan, verifikasi, dan pelajaran. "
+            "Boleh menambahkan transisi atau kalimat penghubung ringan selama tetap berada dalam konteks yang diberikan. "
+            "Jika draft pendek, tetap poles draft yang ada tanpa meminta konteks tambahan. "
+            "Jangan memberi contoh, template, penjelasan, atau catatan editor. "
+            "Kembalikan hanya Markdown final."
+        )
+    return (
+        "You are a technical editor for Vibe2Blog. "
+        "Polish the Markdown draft so it reads more natural, specific, and human. "
+        "Preserve all factual claims, Markdown structure, YAML frontmatter, headings, "
+        "file names, commands, verification results, and code blocks. "
+        "Do not create YAML frontmatter, dates, authors, tags, or metadata when the draft does not already include them. "
+        "Do not invent tests, files, APIs, decisions, outcomes, or new details. "
+        "Remove generic AI phrasing and improve narrative flow. "
+        "Shape the draft as a technical story: problem, investigation, discovery moment, change, verification, and lesson. "
+        "You may add light transitions or connective sentences as long as they stay inside the supplied context. "
+        "If the draft is short, polish only the draft provided without asking for more context. "
+        "Do not provide examples, templates, explanations, or editor notes. "
+        "Return only the final Markdown."
+    )
+
+
+def build_polish_user_prompt(markdown: str, context: SessionContext) -> str:
+    """Provide style context and the bounded draft to rewrite."""
+    return f"""Language: {context.language}
+Editorial mode: {context.tone}
+Audience: {context.audience}
+
+Rewrite this Markdown draft according to the system instructions.
+Return the edited version of this exact draft only.
+
+Draft:
+{markdown[:16000]}
+"""
+
+
+def maybe_polish_markdown(markdown: str, context: SessionContext) -> str:
+    """Apply Modal polish when configured, otherwise return the original draft."""
+    if not should_polish_with_modal():
+        return markdown
+    polished = polish_markdown_with_modal(markdown, context)
+    return polished or markdown

vibe2blog/pipeline.py

@@ -6,6 +6,7 @@ from .context import SessionContext, normalize_context
 from .exporter import write_markdown
 from .extractor import maybe_extract_session_summary
 from .generator import ArticleGenerator, GenerationResult, get_default_generator
+from .modal_polisher import STORYTELLING_TONE, should_polish_with_modal, maybe_polish_markdown
 from .redactor import redact_secrets
 from .validator import ValidationResult, validate_markdown
 
@@ -40,6 +41,23 @@ def build_context_with_redaction(**kwargs: object) -> SessionContext:
     )
 
 
+def build_storytelling_context(context: SessionContext) -> SessionContext:
+    """Use one editorial mode for Modal-backed human storytelling output."""
+    return SessionContext(
+        topic=context.topic,
+        session_summary=context.session_summary,
+        transcript_excerpt=context.transcript_excerpt,
+        git_diff=context.git_diff,
+        verification_notes=context.verification_notes,
+        language=context.language,
+        tone=STORYTELLING_TONE,
+        audience=context.audience,
+        include_code_snippets=context.include_code_snippets,
+        include_frontmatter=context.include_frontmatter,
+        editorial_quality_pass=context.editorial_quality_pass,
+    )
+
+
 def generate_article(
     *,
     generator: ArticleGenerator | None = None,
@@ -48,8 +66,20 @@ def generate_article(
 ) -> PipelineResult:
     """Run the full article flow: context prep, generation, validation, and export."""
     context = build_context_with_redaction(**kwargs)
+    modal_storytelling = should_polish_with_modal()
+    generation_context = build_storytelling_context(context) if modal_storytelling else context
     active_generator = generator or get_default_generator()
-    generation = active_generator.generate(context)
+    generation = active_generator.generate(generation_context)
+    if modal_storytelling:
+        polished_markdown = maybe_polish_markdown(generation.markdown, generation_context)
+        if polished_markdown != generation.markdown:
+            generation = GenerationResult(
+                markdown=polished_markdown,
+                title=generation.title,
+                quality_notes=f"{generation.quality_notes} Modal polish applied.",
+                prompt=generation.prompt,
+                provider=f"{generation.provider}+modal-polish",
+            )
     validation = validate_markdown(
         generation.markdown,
         require_frontmatter=context.include_frontmatter,