Run SmolGPT-Fables v1 with the updated character Studio

Pins the published v1 model commit, adds the shared prompt contract, keeps separate Name/About character cards, and preloads the ZeroGPU model.

README.md

@@ -7,7 +7,7 @@ sdk: gradio
 sdk_version: 6.19.0
 app_file: app.py
 pinned: false
-python_version: "3.11"
+python_version: "3.12.12"
 ---
 
 # SmolGPT-Fables Studio
@@ -21,11 +21,13 @@ This Studio targets the first public release, **SmolGPT-Fables v1**. Future
 model improvements advance as v2, v3, and later releases; the corpus generator's
 internal version is tracked separately.
 
+Training stories: [SmolGPT-Fables Stories](https://huggingface.co/datasets/neonforestmist/smolgpt-markdown-stories).
+
 The Space never substitutes a remote language model or canned story when its model is missing. It reports the missing artifact and stops.
 
 The hosted dependency profile pins Torch 2.11.0, one of the versions supported
 by Hugging Face ZeroGPU. The real story-generation callback is decorated with
-`@spaces.GPU(duration=60)`. The write button calls that function directly as one
+`@spaces.GPU(duration=120)`. The write button calls that function directly as one
 queued event, so form preparation, generation, presentation, and download
 creation share one success or error result. Local environments use a no-op
 fallback for the decorator and continue to select CPU, CUDA, or MPS normally.
@@ -47,7 +49,7 @@ fallback for the decorator and continue to select CPU, CUDA, or MPS normally.
 - Keeps its schema-compatible Markdown canvas and model settings hidden from the writer.
 - Accepts a free-form genre or style and keeps additional story choices optional.
 - Converts ordinary character notes into the model's trained document structure.
-- Loads the Transformers-compatible custom decoder and byte-level BPE tokenizer.
+- Loads a standard Transformers causal LM or the legacy reviewed custom decoder.
 - Labels the result area **SmolGPT-Fables Output:** and shows only the
   reader-facing title and story while retaining the full internal document in
   hidden state.
@@ -58,71 +60,64 @@ fallback for the decorator and continue to select CPU, CUDA, or MPS normally.
 
 ## What to expect from the model
 
-The Studio currently loads a 62,930,560-parameter bootstrap checkpoint at
-optimizer step 3,000. Its sealed 30-prompt synthetic audit reached
-100% schema validity, 86.7% exact scene-count adherence, and 97.0% macro
-required-anchor recall on familiar synthetic constituents. A later novel-name
-Studio regression failed, so this checkpoint is not tagged as v1 and is being
-replaced by the v5 warm-start line. The Space shows generated text without silently
+SmolGPT-Fables v1 is the model used by this Studio. The selected model card is
+the source of truth for its base model, parameter count, training step, and
+measured evaluation results. The Space shows generated text without silently
 replacing it with another model, canned prose, or editorial rewriting.
 
-This remains an experimental small model, not a production writing assistant.
-The final release must pass both synthetic held-out gates and the separate
-Studio-native novelty gate. Those checks do not prove
-literary quality, factuality, safety, or broad reasoning. Review and rewrite
-every result before sharing or publishing it.
+The published checks do not prove literary quality, factuality, safety, or
+broad reasoning. Review and rewrite every result before sharing it.
 
 ## Model artifact
 
-Set one of these Space variables:
+The hosted Studio loads one exact public model revision:
+
+`neonforestmist/smolgpt-fables@4245b8a4359e4490be58aaf8ac919dc371b6570e`
+
+Local runs can use these variables:
 
 | Variable | Purpose |
 | --- | --- |
-| `SMOLGPT_MODEL_REPO` | Hugging Face repository containing the custom model artifact; defaults to `neonforestmist/smolgpt-fables` |
-| `SMOLGPT_MODEL_REVISION` | Optional branch, tag, or commit |
 | `SMOLGPT_MODEL_DIR` | Local artifact directory when running outside Hugging Face |
 | `SMOLGPT_DEVICE` | Optional `auto`, `cpu`, `cuda`, or `mps` |
-| `HF_TOKEN` | Optional secret for a private model repository |
 
 The model repository must contain:
 
 ```text
 model.safetensors          safe model weights
-config.json                architecture values and auto_map
-configuration_smolgpt.py   Transformers configuration class
-modeling_smolgpt.py        Transformers causal language model class
-tokenizer.json             byte-level BPE tokenizer
-```
-
-The Space resolves `SMOLGPT_MODEL_DIR` first. Otherwise it downloads `SMOLGPT_MODEL_REPO`, then loads `AutoTokenizer` and `AutoModelForCausalLM` from the resolved directory. The model and tokenizer are never fetched from another repository.
-
-The weights use Safetensors. The custom architecture is loaded with `trust_remote_code=True`, so the Space operator must choose and review the model repository. Treat `SMOLGPT_MODEL_REPO` as trusted executable code, not as untrusted user input.
-
-The checked-in fallback is `neonforestmist/smolgpt-fables`. An environment variable still overrides it.
-
-## Publish all three repositories in two commands
-
-From the companion project root:
-
-```bash
-hf auth login
-python scripts/publish_hf.py --namespace YOUR_HF_USERNAME
-```
-
-The publisher replaces `neonforestmist` in a temporary staging copy, then creates
-and uploads the model, dataset, and Space repositories. Add a private model's
-`HF_TOKEN` through Hugging Face Settings, never in this repository.
-
-If the Hub returns HTTP 402 while creating this Gradio Space, the destination
-account is not currently entitled to dynamic CPU Spaces. The already uploaded
-model and dataset remain intact. After enabling Gradio Space hosting, retry only
-this artifact:
-
-```bash
-python scripts/publish_hf.py --namespace YOUR_HF_USERNAME --only space
+config.json                standard architecture values or legacy auto_map
+tokenizer.json             matching tokenizer
+configuration_smolgpt.py   legacy custom exports only
+modeling_smolgpt.py        legacy custom exports only
 ```
 
-A static Space cannot run this Python model.
+Outside Hugging Face, the Space resolves `SMOLGPT_MODEL_DIR` first. The hosted
+Space always downloads the exact public revision above, then loads
+`AutoTokenizer` and `AutoModelForCausalLM` from that resolved directory. The
+model and tokenizer are never fetched from another repository.
+
+The weights use Safetensors. Standard architectures load without remote code.
+Legacy custom exports conditionally use `trust_remote_code=True` for local
+reproducibility only.
+
+The current v1 runtime contract is a standard `LlamaForCausalLM` artifact built
+from `HuggingFaceTB/SmolLM2-1.7B-Instruct` and fine-tuned on the audited
+natural-v6 curriculum. It requires `tokenizer_config.json` with the reviewed
+chat template and `training_manifest.json` with the exact natural-v6
+prompt-contract digest. Both must match the selected model bytes. Unknown,
+incomplete, conflicting, or modified contract bindings are rejected before
+generation.
+
+The checked-in hosted model is `neonforestmist/smolgpt-fables` at the exact v1
+commit shown above.
+
+## Release review
+
+The dataset, model, and Space use separate guarded release flows. The dataset is
+added without replacing existing configs. The model must be a promoted,
+checksummed natural-v6 artifact, and the Space is updated only after its exact
+model commit is known. See `docs/09-HUGGING-FACE.md` in the companion project for
+the current review commands. A static Space cannot run this Python model.
 
 ## Local checks
 

app.py

@@ -1,8 +1,11 @@
-"""SmolGPT-Fables Studio, a Hugging Face Gradio Space for custom model artifacts.
-
-The Space loads the project's Transformers-compatible custom architecture from
-the chosen local directory or Hugging Face repository. Text generation never
-falls back to canned prose or a different remote model.
+"""SmolGPT-Fables Studio for standard and legacy Transformers model artifacts.
+
+The hosted Studio loads one canonical, immutable model revision. Local model
+directories remain available outside Hugging Face Spaces so the reviewed
+evaluation workflow can exercise the exact same generation code. Standard
+Transformers models use their native architecture and chat template; legacy
+SmolGPT exports retain the reviewed custom-code path. Text generation never
+falls back to canned prose.
 """
 
 from __future__ import annotations
@@ -10,8 +13,10 @@ from __future__ import annotations
 import hashlib
 import html
 import json
+import math
 import os
 import re
+import sys
 import tempfile
 import threading
 from dataclasses import dataclass
@@ -39,17 +44,27 @@ from transformers import AutoModelForCausalLM, AutoTokenizer
 
 
 SPACE_ROOT = Path(__file__).resolve().parent
+if str(SPACE_ROOT) not in sys.path:
+    sys.path.insert(0, str(SPACE_ROOT))
+
+from runtime_contract import (  # noqa: E402
+    CHAT_PROMPT_FORMAT,
+    PRODUCT_CONTEXT_LENGTH,
+    RAW_PROMPT_FORMAT,
+    SMOLLM3_CHAT_PROMPT_FORMAT,
+    SMOLLM3_PRODUCT_CONTEXT_LENGTH,
+    generation_prompt_ids,
+    product_context_length_for_prompt_format,
+    prompt_format_for_artifact,
+    validate_transformers_artifact,
+)
+
 FONT_DIR = SPACE_ROOT / "assets" / "fonts"
 gr.set_static_paths(paths=[FONT_DIR])
 
-MODEL_ARTIFACT_FILES = (
-    "model.safetensors",
-    "config.json",
-    "configuration_smolgpt.py",
-    "modeling_smolgpt.py",
-    "tokenizer.json",
-)
 DEFAULT_MODEL_REPO = "neonforestmist/smolgpt-fables"
+# Exact SmolGPT-Fables v1 commit published on the model repository's main branch.
+DEFAULT_MODEL_REVISION = "4245b8a4359e4490be58aaf8ac919dc371b6570e"
 RELEASE_VERSION = "v1"
 STORY_STRUCTURES = (
     "in-medias-res",
@@ -149,11 +164,48 @@ class ModelBundle:
     tokenizer: Any
     device: torch.device
     model_dir: Path
+    prompt_format: str = RAW_PROMPT_FORMAT
+
+
+@dataclass(frozen=True)
+class GenerationTrace:
+    """Exact token-boundary telemetry captured before continuation decoding."""
+
+    requested_token_budget: int
+    effective_token_budget: int
+    emitted_continuation_token_count: int
+    stop_reason: str
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    """Decoded continuation plus its exact, generation-time token trace."""
+
+    continuation: str
+    trace: GenerationTrace
 
 
 _MODEL_BUNDLE: Optional[ModelBundle] = None
 
 
+def _running_on_huggingface_space() -> bool:
+    """Return whether Hugging Face has identified this process as a Space."""
+
+    return bool(os.getenv("SPACE_ID", "").strip())
+
+
+def _default_model_revision_is_sealed() -> bool:
+    return re.fullmatch(r"[0-9a-f]{40}", DEFAULT_MODEL_REVISION) is not None
+
+
+def _require_sealed_default_model_revision() -> None:
+    if not _default_model_revision_is_sealed():
+        raise ArtifactError(
+            "The hosted SmolGPT-Fables model revision is not sealed yet. "
+            "Publish and merge the promoted model before launching the Studio."
+        )
+
+
 def _select_device() -> torch.device:
     requested = os.getenv("SMOLGPT_DEVICE", "auto").strip().lower()
     if requested == "auto":
@@ -175,59 +227,40 @@ def _select_device() -> torch.device:
 
 def _resolve_model_root(download: bool) -> Path:
     local_value = os.getenv("SMOLGPT_MODEL_DIR", "").strip()
-    repo_id = os.getenv("SMOLGPT_MODEL_REPO", DEFAULT_MODEL_REPO).strip()
     if local_value:
+        if _running_on_huggingface_space():
+            raise ArtifactError(
+                "Hosted SmolGPT-Fables does not accept a local model override."
+            )
         root = Path(local_value).expanduser().resolve()
         if not root.is_dir():
             raise ArtifactError(f"SMOLGPT_MODEL_DIR is not a directory: {root}")
         return root
-    if repo_id:
-        if not download:
-            raise ArtifactError(
-                "The Hugging Face model is configured and will download on first generation."
+    _require_sealed_default_model_revision()
+    if not download:
+        raise ArtifactError(
+            "The pinned Hugging Face model will download on first generation."
+        )
+    try:
+        return Path(
+            snapshot_download(
+                repo_id=DEFAULT_MODEL_REPO,
+                revision=DEFAULT_MODEL_REVISION,
+                token=os.getenv("HF_TOKEN") or None,
             )
-        try:
-            return Path(
-                snapshot_download(
-                    repo_id=repo_id,
-                    revision=os.getenv("SMOLGPT_MODEL_REVISION") or None,
-                    token=os.getenv("HF_TOKEN") or None,
-                )
-            ).resolve()
-        except Exception as exc:
-            raise ArtifactError(
-                f"Could not download model repository {repo_id}: {exc}"
-            ) from exc
-    raise ArtifactError(
-        "No model is configured. Set SMOLGPT_MODEL_DIR to a local artifact "
-        "directory or SMOLGPT_MODEL_REPO to a Hugging Face model repository."
-    )
+        ).resolve()
+    except Exception as exc:
+        raise ArtifactError(
+            "Could not download the pinned SmolGPT-Fables model "
+            f"{DEFAULT_MODEL_REPO}@{DEFAULT_MODEL_REVISION}: {exc}"
+        ) from exc
 
 
 def _validate_model_root(root: Path) -> Mapping[str, Any]:
-    missing = [name for name in MODEL_ARTIFACT_FILES if not (root / name).is_file()]
-    if missing:
-        raise ArtifactError(
-            "The model repository is missing: " + ", ".join(missing)
-        )
     try:
-        raw_config = json.loads((root / "config.json").read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise ArtifactError(f"Could not read config.json: {exc}") from exc
-    if not isinstance(raw_config, Mapping):
-        raise ArtifactError("config.json must contain a JSON object.")
-    auto_map = raw_config.get("auto_map")
-    if not isinstance(auto_map, Mapping):
-        raise ArtifactError("config.json needs an auto_map for the custom architecture.")
-    missing_auto = [
-        name
-        for name in ("AutoConfig", "AutoModelForCausalLM")
-        if not isinstance(auto_map.get(name), str) or not auto_map.get(name)
-    ]
-    if missing_auto:
-        raise ArtifactError(
-            "config.json auto_map is missing: " + ", ".join(missing_auto)
-        )
+        raw_config, _artifact_kind = validate_transformers_artifact(root)
+    except ValueError as exc:
+        raise ArtifactError(str(exc)) from exc
     return raw_config
 
 
@@ -237,25 +270,32 @@ def load_model_bundle(force: bool = False) -> ModelBundle:
         if _MODEL_BUNDLE is not None and not force:
             return _MODEL_BUNDLE
         root = _resolve_model_root(download=True)
-        _validate_model_root(root)
+        try:
+            _raw_config, artifact_kind = validate_transformers_artifact(root)
+        except ValueError as exc:
+            raise ArtifactError(str(exc)) from exc
         device = _select_device()
         try:
             tokenizer = AutoTokenizer.from_pretrained(
                 str(root),
                 local_files_only=True,
-                trust_remote_code=True,
+                trust_remote_code=artifact_kind == "custom",
             )
             model = AutoModelForCausalLM.from_pretrained(
                 str(root),
                 local_files_only=True,
-                trust_remote_code=True,
+                trust_remote_code=artifact_kind == "custom",
             )
         except Exception as exc:
             raise ArtifactError(
-                "Transformers could not load the custom SmolGPT artifact: " + str(exc)
+                "Transformers could not load the selected SmolGPT artifact: " + str(exc)
             ) from exc
         if tokenizer.bos_token_id is None or tokenizer.eos_token_id is None:
             raise ArtifactError("The tokenizer needs BOS and EOS token IDs.")
+        try:
+            prompt_format = prompt_format_for_artifact(root, artifact_kind, tokenizer)
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            raise ArtifactError(f"Model prompt contract is invalid: {exc}") from exc
         model.to(device)
         model.eval()
         _MODEL_BUNDLE = ModelBundle(
@@ -263,6 +303,7 @@ def load_model_bundle(force: bool = False) -> ModelBundle:
             tokenizer=tokenizer,
             device=device,
             model_dir=root,
+            prompt_format=prompt_format,
         )
         return _MODEL_BUNDLE
 
@@ -288,8 +329,13 @@ def model_status_html() -> str:
             "ready", "SmolGPT is ready.", "Start with an idea whenever you are ready."
         )
     local_value = os.getenv("SMOLGPT_MODEL_DIR", "").strip()
-    repo_id = os.getenv("SMOLGPT_MODEL_REPO", DEFAULT_MODEL_REPO).strip()
     if local_value:
+        if _running_on_huggingface_space():
+            return _status_panel(
+                "error",
+                "Hosted model override rejected",
+                "This Studio only loads its reviewed, pinned model revision.",
+            )
         root = Path(local_value).expanduser()
         if not root.is_dir():
             return _status_panel(
@@ -304,16 +350,16 @@ def model_status_html() -> str:
             "Getting SmolGPT ready...",
             "The story model will load when you write your first story.",
         )
-    if repo_id:
+    if not _default_model_revision_is_sealed():
         return _status_panel(
-            "waiting",
-            "Getting SmolGPT ready...",
-            "The story model will load when you write your first story.",
+            "error",
+            "Studio release is not sealed",
+            "The promoted model must be merged and pinned before this Studio can run.",
         )
     return _status_panel(
-        "error",
-        "Model not configured",
-        "Set SMOLGPT_MODEL_DIR or SMOLGPT_MODEL_REPO before generating a story.",
+        "waiting",
+        "Getting SmolGPT ready...",
+        "The pinned story model will load when you write your first story.",
     )
 
 
@@ -342,9 +388,82 @@ def finish_story_request() -> Tuple[Dict[str, Any], Dict[str, Any]]:
     )
 
 
-def toggle_advanced_options(enabled: Any) -> Dict[str, Any]:
-    """Make advanced settings explicit instead of silently applying hidden values."""
-    return gr.update(visible=bool(enabled))
+def advanced_options_status(enabled: Any) -> str:
+    """Return the visible and screen-reader announced advanced-options state."""
+
+    is_enabled = bool(enabled)
+    state = "On" if is_enabled else "Off"
+    detail = (
+        "Title, viewpoint, story shape, key moments, details, and ending are enabled."
+        if is_enabled
+        else "Simple story defaults are active."
+    )
+    state_class = "advanced-on" if is_enabled else "advanced-off"
+    return (
+        f'<div class="advanced-state {state_class}" role="status" aria-live="polite">'
+        f'<strong>{state}</strong><span>{detail}</span></div>'
+    )
+
+
+def toggle_advanced_options(enabled: Any) -> Tuple[Dict[str, Any], str]:
+    """Show the advanced panel and keep its explicit on/off state synchronized."""
+
+    return gr.update(visible=bool(enabled)), advanced_options_status(enabled)
+
+
+def _step_scene_count(value: Any, delta: int) -> Tuple[int, Dict[str, Any], Dict[str, Any]]:
+    """Move the scene stepper by one and expose disabled endpoint states."""
+
+    if delta not in (-1, 1):
+        raise ValueError("scene stepper delta must be -1 or 1")
+    count = min(MAX_SCENE_COUNT, max(MIN_SCENE_COUNT, _scene_count(value) + delta))
+    return (
+        count,
+        gr.update(interactive=count > MIN_SCENE_COUNT),
+        gr.update(interactive=count < MAX_SCENE_COUNT),
+    )
+
+
+def decrease_scene_count(value: Any) -> Tuple[int, Dict[str, Any], Dict[str, Any]]:
+    return _step_scene_count(value, -1)
+
+
+def increase_scene_count(value: Any) -> Tuple[int, Dict[str, Any], Dict[str, Any]]:
+    return _step_scene_count(value, 1)
+
+
+def sync_scene_stepper(value: Any) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    """Synchronize endpoint buttons while the user edits the numeric value."""
+
+    count = _normalized_scene_stepper_value(value)
+    return (
+        gr.update(interactive=count > MIN_SCENE_COUNT),
+        gr.update(interactive=count < MAX_SCENE_COUNT),
+    )
+
+
+def _normalized_scene_stepper_value(value: Any) -> int:
+    """Round and clamp direct UI input without weakening backend validation."""
+
+    if isinstance(value, bool):
+        return DEFAULT_SCENE_COUNT
+    try:
+        numeric = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_SCENE_COUNT
+    if not math.isfinite(numeric):
+        return DEFAULT_SCENE_COUNT
+    return min(MAX_SCENE_COUNT, max(MIN_SCENE_COUNT, int(round(numeric))))
+
+
+def normalize_scene_stepper(
+    value: Any,
+) -> Tuple[int, Dict[str, Any], Dict[str, Any]]:
+    """Normalize the visible Number when it loses focus and sync endpoints."""
+
+    count = _normalized_scene_stepper_value(value)
+    minus, plus = sync_scene_stepper(count)
+    return count, minus, plus
 
 
 def stop_story_request() -> Tuple[Dict[str, Any], Dict[str, Any], str]:
@@ -419,7 +538,7 @@ def _required_anchor_line(
     characters: str,
     constraints: Optional[str],
 ) -> str:
-    """Match the explicit anchor contract used by the v4 training prompts."""
+    """Match the explicit anchor contract used by the v5 training prompts."""
     anchors: List[str] = []
 
     for match in re.finditer(r"^####\s+(.+?)\s*$", characters, re.MULTILINE):
@@ -455,6 +574,23 @@ def _required_anchor_line(
     return ", ".join(unique)
 
 
+def _explicit_include_anchors(value: Optional[str]) -> List[str]:
+    """Return only the positive details the user explicitly asked to include."""
+    anchors: List[str] = []
+    for raw_line in _text(value).splitlines():
+        line = re.sub(r"^[-*]\s*", "", raw_line.strip()).rstrip(".")
+        lower = line.casefold()
+        if lower.startswith("must include:"):
+            line = line.split(":", 1)[1].strip()
+        elif lower.startswith("include "):
+            line = line[8:].strip()
+        else:
+            continue
+        if line:
+            anchors.append(line)
+    return anchors
+
+
 def _scene_count(value: Any) -> int:
     """Normalize the numeric Studio control to a bounded whole scene count."""
     if isinstance(value, bool):
@@ -533,6 +669,7 @@ def build_canvas(
     ending_target: str,
     structure: str,
     scene_count: Any = DEFAULT_SCENE_COUNT,
+    scene_word_target: Optional[Tuple[int, int]] = None,
 ) -> Tuple[str, str]:
     title = _paragraph(title, "Title")
     genre = _paragraph(genre, "Genre")
@@ -553,6 +690,20 @@ def build_canvas(
         constraints, "Keep the conflict specific and causally resolved."
     )
     required_anchors = _required_anchor_line(setting, characters, constraints)
+    word_target_line = ""
+    if scene_word_target is not None:
+        minimum, maximum = scene_word_target
+        if not (0 < int(minimum) <= int(maximum)):
+            raise StudioError("The hidden scene word target is invalid.")
+        word_target_line = (
+            f"- Aim for {int(minimum)} to {int(maximum)} words in each scene.\n"
+            "- Keep later and final scenes as fully developed as the first; do not "
+            "compress them below the word target.\n"
+            "- In the final scene, explicitly perform the central actions named in "
+            "the story idea, with their objects, and show the result on-page; do "
+            "not end with them merely planned, attempted, promised, or still "
+            "waiting to happen.\n"
+        )
     document = (
         f"# Canvas: {title}\n\n"
         "## Metadata\n\n"
@@ -573,6 +724,7 @@ def build_canvas(
         f"{characters}\n\n"
         "### Constraints\n\n"
         f"- Target scenes: {scene_count}\n"
+        f"{word_target_line}"
         f"- Must include: {required_anchors}.\n"
         f"{constraint_block}\n\n"
         "### Beats\n\n"
@@ -610,7 +762,19 @@ def _plain_character_block(value: Optional[str]) -> str:
     return "\n\n".join(blocks)
 
 
-def _derived_story_title(premise: str, characters: str) -> str:
+def _derived_story_title(
+    premise: str,
+    characters: str,
+    explicit_anchor: str = "",
+    setting: str = "",
+) -> str:
+    if explicit_anchor and setting and setting != "A vivid setting that fits the story idea.":
+        subject = re.sub(r"^(?:a|an|the)\s+", "", explicit_anchor, flags=re.IGNORECASE)
+        place = re.sub(r"^(?:a|an|the)\s+", "", setting, flags=re.IGNORECASE)
+        subject = " ".join(subject.split())[:48].strip()
+        place = " ".join(place.split())[:64].strip()
+        if subject and place:
+            return f"{subject[:1].upper() + subject[1:]} at {place}"
     names = [
         match.group(1).strip()
         for match in re.finditer(r"^####\s+(.+?)\s*$", characters, re.MULTILINE)
@@ -624,8 +788,11 @@ def _derived_story_title(premise: str, characters: str) -> str:
     return " ".join(words).strip() or "A SmolGPT Fable"
 
 
-def _premise_anchor_candidates(premise: str, character_block: str) -> List[str]:
-    """Select a few distinctive premise words so novel objects are copy-signaled."""
+def _premise_anchor_candidates_v1(
+    premise: str, character_block: str
+) -> List[str]:
+    """Reproduce the frozen natural-v6 training prompt contract exactly."""
+
     character_names = {
         match.group(1).strip().casefold()
         for match in re.finditer(r"^####\s+(.+?)\s*$", character_block, re.MULTILINE)
@@ -636,28 +803,167 @@ def _premise_anchor_candidates(premise: str, character_block: str) -> List[str]:
         "their", "there", "these", "those", "through", "together", "under",
         "until", "wants", "where", "which", "while", "would", "young",
     }
-    candidates: List[str] = []
     seen = set()
     for token in re.findall(r"[A-Za-z][A-Za-z'-]+", premise):
         key = token.casefold()
         if len(key) < 6 or key in ignored or key in character_names or key in seen:
             continue
-        seen.add(key)
-        candidates.append(token)
-        if len(candidates) == 3:
+        return [token]
+    return []
+
+
+def _premise_anchor_candidates_v2(premise: str, character_block: str) -> List[str]:
+    """Select a concrete premise phrase so novel objects are copy-signaled."""
+    character_names = {
+        match.group(1).strip().casefold()
+        for match in re.finditer(r"^####\s+(.+?)\s*$", character_block, re.MULTILINE)
+    }
+    character_name_tokens = {
+        token.casefold()
+        for name in character_names
+        for token in re.findall(r"[A-Za-z][A-Za-z'-]+", name)
+    }
+    ignored = {
+        "about", "after", "again", "before", "began", "begins", "being",
+        "caused", "could", "dispute", "find", "finds", "first", "learned",
+        "learns", "marked", "marks", "named",
+        "needs", "points", "reaches", "returns", "return", "sends", "should",
+        "starts", "stolen", "their", "there", "these", "those", "through",
+        "together", "toward", "under", "until", "wants", "where", "which",
+        "while", "would", "young",
+    }
+    phrase_stops = ignored | {
+        "and", "because", "before", "from", "into", "must", "that", "then",
+        "they", "this", "when", "with", "without",
+    }
+    tokens = re.findall(r"[A-Za-z][A-Za-z'-]+", premise)
+    candidates: List[str] = []
+    seen = set()
+    for index, token in enumerate(tokens):
+        key = token.casefold()
+        if (
+            len(key) < 6
+            or key in ignored
+            or key in character_names
+            or key in character_name_tokens
+            or key in seen
+        ):
+            continue
+        phrase = [token]
+        if index + 1 < len(tokens):
+            following = tokens[index + 1]
+            following_key = following.casefold()
+            if (
+                len(following_key) >= 4
+                and following_key not in phrase_stops
+                and following_key not in character_names
+                and following_key not in character_name_tokens
+            ):
+                phrase.append(following)
+        value = " ".join(phrase)
+        seen.add(value.casefold())
+        candidates.append(value)
+        if len(candidates) == 1:
             break
     return candidates
 
 
-def _anchored_fallback_beats(anchor_text: str, scene_count: int) -> str:
-    if not anchor_text:
-        return ""
+def _anchored_fallback_beats_v1(
+    premise: str,
+    setting: str,
+    character_block: str,
+    explicit_anchor: str,
+    premise_anchor: str,
+    scene_count: int,
+) -> str:
+    """Reproduce the frozen natural-v6 fallback plan for historical rows."""
+
+    names = [
+        match.group(1).strip()
+        for match in re.finditer(r"^####\s+(.+?)\s*$", character_block, re.MULTILINE)
+        if match.group(1).strip() and match.group(1).strip() != "Main character"
+    ]
+    team = " and ".join(names) or "The protagonist"
+    verb = "examine" if len(names) != 1 else "examines"
+    artifact = explicit_anchor or premise_anchor or "the central clue"
+    if not re.match(r"^(?:a|an|the|this|that|my|our|their)\s", artifact, re.IGNORECASE):
+        article = "an" if artifact[:1].casefold() in {"a", "e", "i", "o", "u"} else "a"
+        artifact = f"{article} {artifact}"
+    location = setting or "the story's decisive place"
+    if re.match(r"^(?:A|An|The)\s", location):
+        location = location[:1].lower() + location[1:]
+    disruption = premise.rstrip(" .")
+    if re.match(r"^(?:A|An|The)\s", disruption):
+        disruption = disruption[:1].lower() + disruption[1:]
+    lines = [f"At {location}, {team} {verb} {artifact} after {disruption}."]
+    if scene_count == 1:
+        return lines[0]
+    clue = premise_anchor or artifact
+    middle = (
+        f"Following {clue}, the characters revise their plan; the result creates "
+        "a concrete new consequence."
+    )
+    lines.extend([middle] * max(0, scene_count - 2))
+    lines.append(
+        "The protagonist acts on what the evidence revealed, making a visible "
+        "choice that resolves the central conflict."
+    )
+    return "\n".join(lines)
+
+
+def _anchored_fallback_beats_v2(
+    premise: str,
+    setting: str,
+    character_block: str,
+    explicit_anchor: str,
+    premise_anchor: str,
+    scene_count: int,
+) -> str:
+    """Create causal default beats in the same role order as the v5 curriculum."""
+    names = [
+        match.group(1).strip()
+        for match in re.finditer(r"^####\s+(.+?)\s*$", character_block, re.MULTILINE)
+        if match.group(1).strip() and match.group(1).strip() != "Main character"
+    ]
+    team = " and ".join(names) or "The protagonist"
+    plural_team = len(names) >= 2
+    verb = "examine" if plural_team else "examines"
+    test_verb = "test" if plural_team else "tests"
+    combine_verb = "combine" if plural_team else "combines"
+    artifact = explicit_anchor or premise_anchor or "the central clue"
+    if not re.match(r"^(?:a|an|the|this|that|my|our|their)\s", artifact, re.IGNORECASE):
+        article = "an" if artifact[:1].casefold() in {"a", "e", "i", "o", "u"} else "a"
+        artifact = f"{article} {artifact}"
+    location = setting or "the story's decisive place"
+    if re.match(r"^(?:A|An|The)\s", location):
+        location = location[:1].lower() + location[1:]
+    disruption = premise.rstrip(" .")
+    if re.match(r"^(?:A|An|The)\s", disruption):
+        disruption = disruption[:1].lower() + disruption[1:]
+    lines = [f"At {location}, {team} {verb} {artifact} after {disruption}."]
     if scene_count == 1:
-        return f"{anchor_text} become essential to resolving the central conflict."
-    lines = [f"{anchor_text} establish the concrete disruption."]
-    for _ in range(max(0, scene_count - 2)):
-        lines.append("The previous choice creates a concrete new consequence.")
-    lines.append(f"{anchor_text} return in the resolved final choice.")
+        return (
+            f"{lines[0]} In that same scene, the protagonist completes every "
+            "central action named in the story idea, with its object, and shows "
+            "the result."
+        )
+    clue = premise_anchor or artifact
+    middle_beats = (
+        f"{team} {test_verb} what {clue} implies, and the attempt exposes a concrete cost "
+        "nobody expected.",
+        f"A conflicting clue forces {team} to choose between the safe plan and the "
+        "urgent one.",
+        f"The consequence reaches {location}, changing who can be trusted and what "
+        "must happen next.",
+        f"{team} {combine_verb} what each character knows, turning the setback into a "
+        "workable final plan.",
+    )
+    lines.extend(middle_beats[: max(0, scene_count - 2)])
+    lines.append(
+        "The protagonist completes the actions required by the story idea on-page, "
+        "making a visible choice that resolves the central conflict rather than "
+        "merely planning or attempting it."
+    )
     return "\n".join(lines)
 
 
@@ -673,14 +979,23 @@ def prepare_story(
     important_moments: Optional[str],
     details: Optional[str],
     ending_target: Optional[str],
+    planner_version: str = "v1",
 ) -> Tuple[str, str, int]:
-    """Build the hidden model canvas from the Studio's plain-language form."""
+    """Build a model canvas; v1 remains frozen for historical evidence."""
+    if planner_version not in {"v1", "v2"}:
+        raise StudioError("The hidden Studio planner version is invalid.")
     premise = _paragraph(story_idea, "Story idea")
     count = _scene_count(scene_count)
     character_block = _plain_character_block(main_characters)
     resolved_setting = _text(setting) or "A vivid setting that fits the story idea."
     resolved_details = _text(details)
-    inferred_anchors = _premise_anchor_candidates(premise, character_block)
+    anchor_builder = (
+        _premise_anchor_candidates_v2
+        if planner_version == "v2"
+        else _premise_anchor_candidates_v1
+    )
+    inferred_anchors = anchor_builder(premise, character_block)
+    explicit_anchors = _explicit_include_anchors(resolved_details)
     if inferred_anchors:
         inferred_lines = "\n".join(f"Include {anchor}" for anchor in inferred_anchors)
         resolved_details = "\n".join(
@@ -693,7 +1008,12 @@ def prepare_story(
     resolved_title = _text(title)
     if not resolved_title:
         resolved_title = (
-            _derived_story_title(premise, character_block)
+            _derived_story_title(
+                premise,
+                character_block,
+                explicit_anchors[0] if explicit_anchors else "",
+                resolved_setting,
+            )
             if specific_brief
             else "A SmolGPT Fable"
         )
@@ -702,8 +1022,17 @@ def prepare_story(
         character_block,
         resolved_details,
     )
-    resolved_moments = _text(important_moments) or _anchored_fallback_beats(
-        anchor_text,
+    beat_builder = (
+        _anchored_fallback_beats_v2
+        if planner_version == "v2"
+        else _anchored_fallback_beats_v1
+    )
+    resolved_moments = _text(important_moments) or beat_builder(
+        premise,
+        resolved_setting,
+        character_block,
+        explicit_anchors[0] if explicit_anchors else "",
+        inferred_anchors[0] if inferred_anchors else "",
         count,
     )
     canvas, story_input = build_canvas(
@@ -719,10 +1048,42 @@ def prepare_story(
         or "Resolve the central conflict and end with a clear emotional change.",
         _text(structure) or "linear-three-act",
         count,
+        (55, 100) if planner_version == "v2" else None,
     )
     return canvas, story_input, SCENE_TOKEN_BUDGETS[count]
 
 
+def prepare_studio_story(
+    story_idea: Optional[str],
+    genre: Optional[str],
+    scene_count: Any,
+    main_characters: Optional[str],
+    setting: Optional[str],
+    title: Optional[str],
+    point_of_view: Optional[str],
+    structure: Optional[str],
+    important_moments: Optional[str],
+    details: Optional[str],
+    ending_target: Optional[str],
+) -> Tuple[str, str, int]:
+    """Build the current public v2 Studio plan without rebinding v1 corpora."""
+
+    return prepare_story(
+        story_idea,
+        genre,
+        scene_count,
+        main_characters,
+        setting,
+        title,
+        point_of_view,
+        structure,
+        important_moments,
+        details,
+        ending_target,
+        planner_version="v2",
+    )
+
+
 def _story_prompt(canvas: str) -> str:
     text = canvas.strip()
     required = (
@@ -832,12 +1193,12 @@ def _model_context_length(model: Any) -> int:
         if value is not None and int(value) > 0:
             return int(value)
     raise ArtifactError(
-        "The custom model config needs context_length or max_position_embeddings."
+        "The model config needs context_length or max_position_embeddings."
     )
 
 
 @torch.inference_mode()
-def generate_continuation(
+def generate_continuation_with_trace(
     bundle: ModelBundle,
     prompt: str,
     temperature: float,
@@ -847,27 +1208,41 @@ def generate_continuation(
     max_new_tokens: int,
     progress: Optional[gr.Progress] = None,
     stop_strings: Tuple[str, ...] = (),
-) -> str:
+) -> GenerationResult:
+    """Generate text while retaining exact pre-decode completion telemetry."""
+
     tokenizer = bundle.tokenizer
     context_length = _model_context_length(bundle.model)
-    token_ids = [
-        int(tokenizer.bos_token_id),
-        *tokenizer.encode(prompt, add_special_tokens=False),
-    ]
+    prompt_format = getattr(bundle, "prompt_format", RAW_PROMPT_FORMAT)
+    try:
+        contract_context_length = product_context_length_for_prompt_format(
+            prompt_format
+        )
+    except ValueError as exc:
+        raise ArtifactError(str(exc)) from exc
+    if contract_context_length is not None:
+        context_length = min(context_length, contract_context_length)
+    token_ids = generation_prompt_ids(
+        tokenizer,
+        prompt,
+        prompt_format,
+    )
     if len(token_ids) >= context_length:
         raise StudioError(
             f"The prompt uses {len(token_ids)} tokens, but this model supports "
             f"{context_length}. Shorten the canvas or story."
         )
-    if int(max_new_tokens) < 0:
+    requested_budget = int(max_new_tokens)
+    if requested_budget < 0:
         raise StudioError("The story length must be zero or greater.")
     # Stop at the learned position boundary instead of sliding the opening
     # canvas out of view. That keeps names, required details, and scene count in
     # every attention prefix.
-    budget = min(int(max_new_tokens), context_length - len(token_ids))
+    budget = min(requested_budget, context_length - len(token_ids))
     generated: List[int] = []
     past_key_values: Any = None
     cache_active = True
+    stop_reason = "token-budget"
     for index in range(budget):
         step_ids = token_ids if not cache_active or past_key_values is None else token_ids[-1:]
         inputs = torch.tensor([step_ids], dtype=torch.long, device=bundle.device)
@@ -894,7 +1269,7 @@ def generate_continuation(
             outputs = bundle.model(input_ids=inputs)
         logits = getattr(outputs, "logits", None)
         if logits is None:
-            raise StudioError("The custom model did not return causal language logits.")
+            raise StudioError("The model did not return causal language logits.")
         next_cache = getattr(outputs, "past_key_values", None)
         if cache_active and next_cache is None:
             # Models exported before KV-cache support accept extra kwargs but
@@ -902,8 +1277,10 @@ def generate_continuation(
             cache_active = False
         elif cache_active:
             past_key_values = next_cache
+        # Requested names/details live in the prompt and must remain copyable.
+        # Repetition control applies only to tokens emitted by the model.
         prior_ids = torch.tensor(
-            token_ids[-256:], dtype=torch.long, device=bundle.device
+            generated[-256:], dtype=torch.long, device=bundle.device
         )
         value = _sample_next(
             logits[0, -1],
@@ -914,19 +1291,56 @@ def generate_continuation(
             float(repetition_penalty),
         )
         if value == int(tokenizer.eos_token_id):
+            stop_reason = "eos"
             break
         token_ids.append(value)
         generated.append(value)
         if stop_strings:
             partial = tokenizer.decode(generated, skip_special_tokens=True)
             if any(marker in partial for marker in stop_strings):
+                stop_reason = "stop-string"
                 break
         if progress is not None and (index + 1) % 24 == 0:
             progress(
                 (index + 1) / max(budget, 1),
                 desc="Writing your story",
             )
-    return tokenizer.decode(generated, skip_special_tokens=True).strip()
+    continuation = tokenizer.decode(generated, skip_special_tokens=True).strip()
+    return GenerationResult(
+        continuation=continuation,
+        trace=GenerationTrace(
+            requested_token_budget=requested_budget,
+            effective_token_budget=budget,
+            emitted_continuation_token_count=len(generated),
+            stop_reason=stop_reason,
+        ),
+    )
+
+
+def generate_continuation(
+    bundle: ModelBundle,
+    prompt: str,
+    temperature: float,
+    top_p: float,
+    top_k: int,
+    repetition_penalty: float,
+    max_new_tokens: int,
+    progress: Optional[gr.Progress] = None,
+    stop_strings: Tuple[str, ...] = (),
+) -> str:
+    """Backward-compatible Studio text path; telemetry is available separately."""
+
+    return generate_continuation_with_trace(
+        bundle,
+        prompt,
+        temperature,
+        top_p,
+        top_k,
+        repetition_penalty,
+        max_new_tokens,
+        progress=progress,
+        stop_strings=stop_strings,
+    ).continuation
 
 
 def _story_filename(story: str) -> str:
@@ -982,7 +1396,7 @@ def _generate_story_document(
     )
 
 
-@spaces.GPU(duration=60)
+@spaces.GPU(duration=120)
 def generate_story(
     canvas: str,
     temperature: float,
@@ -1008,7 +1422,7 @@ def generate_story(
         raise _ui_error(f"Story generation failed: {exc}") from exc
 
 
-@spaces.GPU(duration=60)
+@spaces.GPU(duration=120)
 def write_story_from_form(
     story_idea: Optional[str],
     genre: Optional[str],
@@ -1030,7 +1444,7 @@ def write_story_from_form(
     """Run the complete public Studio flow as one reliable queued event."""
     try:
         use_advanced = bool(advanced_enabled)
-        _, story_input, max_new_tokens = prepare_story(
+        _, story_input, max_new_tokens = prepare_studio_story(
             story_idea,
             genre,
             scene_count,
@@ -1370,8 +1784,7 @@ body { min-height: 100dvh; }
   opacity: .62;
 }
 
-.story-shape .wrap,
-.story-shape [role="radiogroup"] {
+.story-shape fieldset:has(input[type="radio"]) > .wrap {
   display: grid !important;
   grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 8px !important;
@@ -1567,8 +1980,7 @@ footer { display: none !important; }
   .character-row { width: 100%; }
   .character-row > .character-row { padding: 10px !important; }
   .story-stage { min-height: 320px; }
-  .story-shape .wrap,
-  .story-shape [role="radiogroup"] {
+  .story-shape fieldset:has(input[type="radio"]) > .wrap {
     grid-template-columns: 1fr;
   }
   .status-panel { grid-template-columns: 1fr; gap: 5px; }
@@ -1596,6 +2008,7 @@ footer { display: none !important; }
   --color-text: #111827;
   --color-muted: #4b5563;
   --color-success: #16a34a;
+  --color-success-ink: #0f6b31;
   --color-warning: #d97706;
   --color-danger: #dc2626;
   --color-line: rgba(38, 61, 91, .32);
@@ -1627,8 +2040,10 @@ footer { display: none !important; }
   --color-canvas: #0d1726;
   --color-text: #f8fafc;
   --color-muted: #cbd5e1;
+  --color-secondary: #b9eaff;
   --color-line: rgba(148, 196, 219, .48);
   --color-focus: #82d9f7;
+  --color-success-ink: #86efac;
   --studio-panel: #1b2d45;
   --studio-bg: var(--color-canvas);
   --studio-paper: var(--color-surface);
@@ -1672,6 +2087,13 @@ footer { display: none !important; }
   gap: var(--space-8) !important;
 }
 .character-list { gap: var(--space-3) !important; }
+.character-list .character-list > .styler {
+  display: grid !important;
+  grid-template-columns: minmax(0, 1fr) !important;
+  gap: var(--space-3) !important;
+  width: 100% !important;
+  min-width: 0 !important;
+}
 .character-card {
   position: relative;
   padding: var(--space-3) !important;
@@ -1704,10 +2126,11 @@ footer { display: none !important; }
   border-color: var(--color-secondary) !important;
   box-shadow: var(--sketch-shadow), 0 0 0 3px rgba(73, 182, 229, .28) !important;
 }
-.story-shape .wrap,
-.story-shape [role="radiogroup"] { grid-template-columns: 1fr !important; }
+.story-shape fieldset:has(input[type="radio"]) > .wrap {
+  grid-template-columns: 1fr !important;
+}
 .story-shape label,
-.gradio-container [role="radiogroup"] label { min-height: 44px !important; }
+.gradio-container label:has(input[type="radio"]) { min-height: 44px !important; }
 .studio-primary {
   color: #111827 !important;
   border: 1.5px solid var(--color-secondary) !important;
@@ -1735,7 +2158,7 @@ footer { display: none !important; }
 .gradio-container input:focus-visible,
 .gradio-container textarea:focus-visible,
 .gradio-container [role="radio"]:focus-visible,
-.gradio-container [role="radiogroup"] label:focus-within,
+.gradio-container label:has(input[type="radio"]):focus-within,
 .gradio-container summary:focus-visible,
 .gradio-container [role="tab"]:focus-visible,
 .gradio-container input[type="file"]:focus-visible {
@@ -1768,8 +2191,18 @@ footer { display: none !important; }
 .character-list #character-1-card:has(.character-card)::before { content: "1"; }
 .character-list #character-2-card:has(.character-card)::before { content: "2"; }
 .character-card .character-card::before { display: none !important; }
-.character-card textarea { min-height: 68px !important; resize: vertical; }
+.character-card textarea { max-width: 100% !important; }
+.character-name-field textarea {
+  min-height: 44px !important;
+  height: 44px !important;
+  resize: none !important;
+}
+.character-about-field textarea {
+  min-height: 72px !important;
+  resize: vertical;
+}
 .character-card input { min-height: 44px !important; }
+.character-card .form { gap: var(--space-2) !important; }
 
 /* Selected story choices need an unmistakable filled center dot. */
 .gradio-container input[type="radio"] {
@@ -1786,7 +2219,7 @@ footer { display: none !important; }
 }
 .gradio-container input[type="radio"]:checked {
   border-color: var(--color-primary) !important;
-  background: radial-gradient(circle, var(--color-primary) 0 38%, transparent 42% 100%) !important;
+  background: radial-gradient(circle at center, var(--color-primary) 0 5px, var(--color-surface) 5.5px 100%) !important;
 }
 .gradio-container label:has(input[type="radio"]:checked) {
   border-color: var(--color-primary) !important;
@@ -1813,18 +2246,283 @@ footer { display: none !important; }
 .advanced-toggle input[type="checkbox"]:checked {
   background: radial-gradient(circle at 32px 50%, #ffffff 0 7px, transparent 8px), var(--color-primary) !important;
 }
-.advanced-panel {
+.advanced-toggle label {
+  min-height: 48px !important;
+  align-items: center !important;
+  touch-action: manipulation;
+}
+.advanced-panel,
+.advanced-panel .advanced-panel {
+  min-width: 0 !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+}
+.advanced-panel:has(.advanced-panel) {
   margin-top: var(--space-2) !important;
   padding: var(--space-4) !important;
   border: 1.5px dashed var(--color-line) !important;
   border-radius: var(--radius-card) !important;
   background: color-mix(in srgb, var(--studio-panel) 62%, transparent) !important;
 }
+.advanced-panel .advanced-panel > .styler {
+  width: 100% !important;
+  min-width: 0 !important;
+  background: transparent !important;
+}
+
+/* Compact, keyboard-first scene stepper. The full button text remains the
+   accessible name while the drawn symbols stay visually compact. */
+.scene-stepper-field,
+.scene-stepper-field .scene-stepper-field {
+  min-width: 0 !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  border-radius: 0 !important;
+  background: transparent !important;
+  box-shadow: none !important;
+}
+.scene-stepper-field:has(.scene-stepper-field) {
+  padding: var(--space-3) !important;
+  border: 1.5px solid var(--color-line) !important;
+  border-radius: var(--radius-card) !important;
+  background: color-mix(in srgb, var(--studio-panel) 52%, var(--color-surface)) !important;
+  box-shadow: var(--sketch-shadow) !important;
+}
+.scene-stepper-field .scene-stepper-field > .styler {
+  width: 100% !important;
+  min-width: 0 !important;
+  background: transparent !important;
+}
+.scene-stepper-label {
+  min-width: 0 !important;
+  margin: 0 0 var(--space-2) !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+}
+.scene-stepper-label h3 {
+  margin: 0 !important;
+  color: var(--color-text) !important;
+  font-family: "Delius Swash Caps", "Comic Sans MS", cursive !important;
+  font-size: 16px !important;
+  font-weight: 400 !important;
+}
+.scene-stepper-label p {
+  margin: 2px 0 0 !important;
+  color: var(--color-muted) !important;
+  font-size: 13px !important;
+}
+.scene-stepper {
+  display: grid !important;
+  grid-template-columns: 48px minmax(72px, 96px) 48px !important;
+  gap: var(--space-2) !important;
+  justify-content: start !important;
+  align-items: stretch !important;
+  min-width: 0 !important;
+  flex-wrap: nowrap !important;
+}
+.scene-stepper > * { min-width: 0 !important; }
+button.scene-stepper-button,
+.scene-stepper-button > button {
+  width: 48px !important;
+  min-width: 48px !important;
+  min-height: 48px !important;
+}
+.scene-stepper-button,
+.scene-stepper-button button {
+  padding: 0 !important;
+  border: 1.5px solid var(--color-secondary) !important;
+  border-radius: 46% 54% 49% 51% !important;
+  background: var(--color-surface) !important;
+  box-shadow: var(--sketch-shadow) !important;
+  color: var(--color-secondary) !important;
+  font-size: 0 !important;
+  touch-action: manipulation;
+}
+button.scene-stepper-button::before,
+.scene-stepper-button > button::before {
+  display: block;
+  font-family: "JetBrains Mono", ui-monospace, monospace;
+  font-size: 25px;
+  line-height: 1;
+}
+button.scene-stepper-minus::before,
+.scene-stepper-minus > button::before { content: "\2212"; }
+button.scene-stepper-plus::before,
+.scene-stepper-plus > button::before { content: "+"; }
+button.scene-stepper-button:hover:not(:disabled),
+.scene-stepper-button > button:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--color-primary) 22%, var(--color-surface)) !important;
+}
+button.scene-stepper-button:disabled,
+.scene-stepper-button > button:disabled {
+  cursor: not-allowed !important;
+  opacity: .42 !important;
+  box-shadow: none !important;
+}
+.scene-stepper-value {
+  width: 100% !important;
+  max-width: 96px !important;
+  min-width: 72px !important;
+}
+.scene-stepper-value input {
+  width: 100% !important;
+  min-height: 48px !important;
+  padding-inline: var(--space-2) !important;
+  border: 1.5px solid var(--color-secondary) !important;
+  border-radius: var(--radius-control) !important;
+  background: var(--color-surface) !important;
+  color: var(--color-text) !important;
+  font-family: "JetBrains Mono", ui-monospace, monospace !important;
+  font-size: 22px !important;
+  font-variant-numeric: tabular-nums;
+  text-align: center !important;
+  appearance: textfield;
+}
+.scene-stepper-value input::-webkit-inner-spin-button,
+.scene-stepper-value input::-webkit-outer-spin-button {
+  margin: 0;
+  appearance: none;
+}
+
+.advanced-toggle label:has(input[type="checkbox"]:checked) {
+  border-radius: var(--radius-control) !important;
+  background: color-mix(in srgb, var(--color-primary) 24%, var(--color-surface)) !important;
+}
+.advanced-status {
+  min-width: 0 !important;
+  margin: calc(-1 * var(--space-2)) 0 var(--space-2) !important;
+  padding: 0 var(--space-3) var(--space-2) !important;
+  border: 0 !important;
+  background: transparent !important;
+}
+.advanced-state {
+  display: flex;
+  gap: var(--space-2);
+  align-items: baseline;
+  min-width: 0;
+  color: var(--color-muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+.advanced-state strong {
+  flex: 0 0 auto;
+  min-width: 42px;
+  padding: 2px var(--space-2);
+  border: 1px solid var(--color-line);
+  border-radius: 999px;
+  background: var(--color-surface);
+  color: var(--color-text);
+  font-family: "JetBrains Mono", ui-monospace, monospace;
+  font-size: 12px;
+  line-height: 1.5;
+  text-align: center;
+}
+.advanced-state.advanced-on strong {
+  border-color: var(--color-success-ink);
+  color: var(--color-success-ink);
+}
+.advanced-state span { min-width: 0; overflow-wrap: anywhere; }
+
+/* In Gradio 6 the advanced radio inputs inherit a fluid input width. Pin the
+   indicator and let the human-readable label take the remaining 410px column. */
+.advanced-panel fieldset:has(input[type="radio"]) > .wrap {
+  display: grid !important;
+  grid-template-columns: minmax(0, 1fr) !important;
+  gap: var(--space-2) !important;
+  width: 100% !important;
+  min-width: 0 !important;
+}
+.advanced-panel label:has(input[type="radio"]) {
+  display: flex !important;
+  flex-flow: row nowrap !important;
+  gap: var(--space-2) !important;
+  align-items: center !important;
+  justify-content: flex-start !important;
+  width: 100% !important;
+  min-width: 0 !important;
+  min-height: 48px !important;
+  padding: var(--space-2) var(--space-3) !important;
+  box-sizing: border-box !important;
+  word-break: normal !important;
+}
+.advanced-panel input[type="radio"] {
+  flex: 0 0 20px !important;
+  width: 20px !important;
+  max-width: 20px !important;
+  min-width: 20px !important;
+}
+.advanced-panel label:has(input[type="radio"]) > span {
+  flex: 1 1 auto !important;
+  width: auto !important;
+  min-width: 0 !important;
+  max-width: 100% !important;
+  white-space: normal !important;
+  word-break: normal !important;
+  overflow-wrap: break-word !important;
+}
+
+/* Gradio controls must shrink inside cards instead of forcing horizontal
+   overflow. Menus stay inside the viewport and touch targets remain 44px. */
+.creator-grid > *,
+.creator-form > *,
+.character-list > *,
+.character-card,
+.advanced-panel,
+.story-actions,
+.story-shape,
+.studio-select,
+.gradio-container .form,
+.gradio-container .wrap {
+  min-width: 0 !important;
+  max-width: 100% !important;
+  box-sizing: border-box !important;
+}
+.gradio-container label:has(input[type="radio"]),
+.gradio-container [role="option"],
+.gradio-container button {
+  overflow-wrap: anywhere;
+  white-space: normal !important;
+}
+.gradio-container [role="listbox"] {
+  width: min(100%, calc(100vw - 24px)) !important;
+  max-width: calc(100vw - 24px) !important;
+  max-height: min(360px, 60vh) !important;
+  overflow: auto !important;
+}
+.character-card input,
+.character-card textarea,
+.advanced-panel input,
+.advanced-panel textarea {
+  width: 100% !important;
+  max-width: 100% !important;
+  box-sizing: border-box !important;
+}
 
 @media (max-width: 900px) {
   .creator-grid { grid-template-columns: minmax(0, 1fr); }
 }
 
+@media (max-width: 520px) {
+  .gradio-container { padding-inline: 10px !important; }
+  .scene-stepper { justify-content: center !important; }
+  .character-card:has(.character-card),
+  .advanced-panel:has(.advanced-panel),
+  .scene-stepper-field:has(.scene-stepper-field) { padding: var(--space-3) !important; }
+  .story-actions {
+    display: grid !important;
+    grid-template-columns: minmax(0, 1fr) !important;
+  }
+  .story-actions > *,
+  .story-actions button { width: 100% !important; min-width: 0 !important; }
+  .advanced-state { align-items: flex-start; }
+}
+
 .main.fillable.app {
   width: min(calc(100vw - 32px), 1280px) !important;
   margin-inline: auto !important;
@@ -1863,7 +2561,7 @@ def build_demo() -> gr.Blocks:
             <header class="studio-head">
               <h1>SmolGPT-Fables Studio</h1>
               <svg class="studio-squiggle" viewBox="0 0 330 14" aria-hidden="true" focusable="false"><path d="M2 9 C 48 1, 84 13, 128 7 S 220 4, 328 8" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round"/></svg>
-              <p>Give it an idea and see what this tiny experimental story model writes.</p>
+              <p>Give it an idea and see what this small story model writes.</p>
             </header>
             <div class="studio-rule" aria-hidden="true"></div>
             """
@@ -1896,16 +2594,41 @@ def build_demo() -> gr.Blocks:
                             placeholder="Mystery, romance, folklore, space adventure",
                             info="Use any genre or mix of styles you like.",
                         )
-                        scene_count = gr.Number(
-                            value=DEFAULT_SCENE_COUNT,
-                            label="How many scenes?",
-                            info="Choose a whole number from 1 to 6.",
-                            minimum=MIN_SCENE_COUNT,
-                            maximum=MAX_SCENE_COUNT,
-                            step=1,
-                            precision=0,
-                            elem_classes="scene-count",
-                        )
+                        with gr.Group(elem_classes="scene-stepper-field"):
+                            gr.Markdown(
+                                "### How many scenes?\nChoose from 1 to 6.",
+                                elem_classes="scene-stepper-label",
+                            )
+                            with gr.Row(elem_classes="scene-stepper"):
+                                scene_minus = gr.Button(
+                                    "Decrease scenes",
+                                    size="sm",
+                                    min_width=48,
+                                    elem_classes=[
+                                        "scene-stepper-button",
+                                        "scene-stepper-minus",
+                                    ],
+                                )
+                                scene_count = gr.Number(
+                                    value=DEFAULT_SCENE_COUNT,
+                                    label="How many scenes?",
+                                    show_label=False,
+                                    container=False,
+                                    step=1,
+                                    precision=0,
+                                    min_width=72,
+                                    elem_id="scene-count-value",
+                                    elem_classes="scene-stepper-value",
+                                )
+                                scene_plus = gr.Button(
+                                    "Increase scenes",
+                                    size="sm",
+                                    min_width=48,
+                                    elem_classes=[
+                                        "scene-stepper-button",
+                                        "scene-stepper-plus",
+                                    ],
+                                )
                         gr.Markdown(
                             "### Main characters\nOne character per card. The second card is optional.",
                             elem_classes="character-heading",
@@ -1920,6 +2643,7 @@ def build_demo() -> gr.Blocks:
                                     placeholder="Mara",
                                     info="Character 1",
                                     lines=1,
+                                    elem_classes="character-name-field",
                                 )
                                 first_character_about = gr.Textbox(
                                     label="About them",
@@ -1928,6 +2652,7 @@ def build_demo() -> gr.Blocks:
                                     ),
                                     info="Role, personality, and what they want.",
                                     lines=2,
+                                    elem_classes="character-about-field",
                                 )
                             with gr.Group(
                                 elem_classes=["character-card", "character-card-optional"],
@@ -1938,12 +2663,14 @@ def build_demo() -> gr.Blocks:
                                     placeholder="Ilyan",
                                     info="Character 2",
                                     lines=1,
+                                    elem_classes="character-name-field",
                                 )
                                 second_character_about = gr.Textbox(
                                     label="About them (optional)",
                                     placeholder="A wandering artist looking for a home",
                                     info="Leave both fields blank for a one-character story.",
                                     lines=2,
+                                    elem_classes="character-about-field",
                                 )
                         setting = gr.Textbox(
                             label="Where does it happen?",
@@ -1953,13 +2680,17 @@ def build_demo() -> gr.Blocks:
 
                         advanced_enabled = gr.Checkbox(
                             value=False,
-                            label="Use advanced options",
+                            label="Advanced options",
                             info=(
                                 "Turn this on to customize the title, viewpoint, "
                                 "story shape, key moments, required details, and ending."
                             ),
                             elem_classes="advanced-toggle",
                         )
+                        advanced_status = gr.HTML(
+                            advanced_options_status(False),
+                            elem_classes="advanced-status",
+                        )
                         with gr.Group(
                             visible=False,
                             elem_classes="advanced-panel",
@@ -2007,7 +2738,36 @@ def build_demo() -> gr.Blocks:
                         advanced_enabled.change(
                             fn=toggle_advanced_options,
                             inputs=advanced_enabled,
-                            outputs=advanced_panel,
+                            outputs=[advanced_panel, advanced_status],
+                            show_progress="hidden",
+                            **PRIVATE_EVENT_ARGS,
+                        )
+
+                        scene_minus.click(
+                            fn=decrease_scene_count,
+                            inputs=scene_count,
+                            outputs=[scene_count, scene_minus, scene_plus],
+                            show_progress="hidden",
+                            **PRIVATE_EVENT_ARGS,
+                        )
+                        scene_plus.click(
+                            fn=increase_scene_count,
+                            inputs=scene_count,
+                            outputs=[scene_count, scene_minus, scene_plus],
+                            show_progress="hidden",
+                            **PRIVATE_EVENT_ARGS,
+                        )
+                        scene_count.input(
+                            fn=sync_scene_stepper,
+                            inputs=scene_count,
+                            outputs=[scene_minus, scene_plus],
+                            show_progress="hidden",
+                            **PRIVATE_EVENT_ARGS,
+                        )
+                        scene_count.blur(
+                            fn=normalize_scene_stepper,
+                            inputs=scene_count,
+                            outputs=[scene_count, scene_minus, scene_plus],
                             show_progress="hidden",
                             **PRIVATE_EVENT_ARGS,
                         )
@@ -2071,7 +2831,7 @@ def build_demo() -> gr.Blocks:
                     """
 ## About SmolGPT-Fables Studio
 
-SmolGPT-Fables Studio is a hands-on demo for the experimental SmolGPT-Fables v1 model. The form keeps its internal document structure out of the way, so you can focus on characters, places, and what happens.
+SmolGPT-Fables Studio is a hands-on demo for SmolGPT-Fables v1. The form keeps its internal document structure out of the way, so you can focus on characters, places, and what happens.
 
 Choose between one and six scenes. The Studio uses that choice to shape the hidden story plan and keep the generation budget proportional to the requested story.
 
@@ -2135,6 +2895,12 @@ This is a focused, text-only story Studio.
     return demo
 
 
+if _running_on_huggingface_space():
+    # ZeroGPU supports CUDA placement during startup and recommends loading the
+    # model outside the decorated request so each story does not reload weights.
+    load_model_bundle()
+
+
 demo = build_demo()
 
 

runtime_contract.py

@@ -0,0 +1,491 @@
+"""Stable prompt and artifact contract shared by the Studio and product SFT."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+
+CHAT_PROMPT_FORMAT = "smolgpt-fables-chat-v3"
+SMOLLM3_CHAT_PROMPT_FORMAT = "smolgpt-fables-smollm3-chat-v5"
+RAW_PROMPT_FORMAT = "smolgpt-fables-raw-v1"
+PRODUCT_CONTEXT_LENGTH = 2048
+SMOLLM3_PRODUCT_CONTEXT_LENGTH = 4096
+CHAT_SYSTEM_PROMPT = (
+    "You are SmolGPT-Fables. Output only the requested finished Markdown story "
+    "continuation. Begin exactly with `### Scene 01:`. Emit exactly the requested "
+    "number of consecutive, zero-padded `### Scene NN:` sections. Those scene "
+    "headings are the only headings allowed in the output: never emit an H1, H2, "
+    "any other H3, an H4 or deeper heading, or any other section before, between, "
+    "or after them. Follow the canvas exactly and copy every required name and "
+    "detail verbatim. Stop immediately after the requested final scene. Never "
+    "repeat or quote the story title, metadata, canvas, `## Story`, or any instruction."
+)
+CHAT_PROMPT_TRANSFORM_VERSION = "scene-output-contract-v1"
+CHAT_STORY_BOUNDARY = "## Story\n\n"
+CHAT_OUTPUT_CONTRACT_TEMPLATE = (
+    "Output contract (follow exactly): use only these H3 heading prefixes, in this "
+    "order: {headings}. Write exactly {scene_count} scenes; emit no other heading "
+    "or section; stop immediately after completing `### Scene {final_scene:02d}:`.\n\n"
+)
+SMOLLM3_PROMPT_TRANSFORM_VERSION = "natural-fable-scene-contract-v3"
+SMOLLM3_STORY_BOUNDARY = "## Story\n\n"
+SMOLLM3_SCENE_WORD_RANGE = (45, 115)
+SMOLLM3_SYSTEM_PROMPT = (
+    "You are SmolGPT-Fables. Write a vivid, complete fable from the user's canvas. "
+    "Output only the finished story continuation. Begin with `### Scene 01:` and "
+    "emit exactly the requested consecutive, zero-padded scene sections. A scene "
+    "heading may include a short title after the colon. Use no other Markdown "
+    "heading. Copy every required name, setting, and unusual detail verbatim. Make "
+    "each character's described role, personality, and desire affect what they do. "
+    "Write concrete action and dialogue instead of summarizing instructions. Keep "
+    "each scene concise, make every scene change the situation, and resolve the "
+    "ending target inside the final scene. Stop immediately after the final sentence; "
+    "never add notes, analysis, a moral label, an ending section, or quoted canvas "
+    "text. /no_think"
+)
+_SCENE_COUNT_PATTERN = re.compile(r"(?m)^- Scene Count: ([0-9]+)$")
+_TARGET_SCENES_PATTERN = re.compile(r"(?m)^- Target scenes: ([0-9]+)$")
+_MIN_SCENE_COUNT = 1
+_MAX_SCENE_COUNT = 6
+SUPPORTED_PROMPT_FORMATS = frozenset(
+    {CHAT_PROMPT_FORMAT, SMOLLM3_CHAT_PROMPT_FORMAT, RAW_PROMPT_FORMAT}
+)
+CHAT_PROMPT_FORMATS = frozenset(
+    {CHAT_PROMPT_FORMAT, SMOLLM3_CHAT_PROMPT_FORMAT}
+)
+COMMON_ARTIFACT_FILES = ("config.json", "tokenizer.json")
+CUSTOM_CODE_FILES = ("configuration_smolgpt.py", "modeling_smolgpt.py")
+
+
+def _render_output_contract(scene_count: int) -> str:
+    headings = ", ".join(
+        f"`### Scene {index:02d}:`" for index in range(1, scene_count + 1)
+    )
+    return CHAT_OUTPUT_CONTRACT_TEMPLATE.format(
+        headings=headings,
+        scene_count=scene_count,
+        final_scene=scene_count,
+    )
+
+
+def prompt_contract_sha256() -> str:
+    payload = {
+        "format": CHAT_PROMPT_FORMAT,
+        "system": CHAT_SYSTEM_PROMPT,
+        "messages": ["system", "user", "assistant"],
+        "assistant_only_loss": True,
+        "prompt_transform": {
+            "version": CHAT_PROMPT_TRANSFORM_VERSION,
+            "scene_count_pattern": _SCENE_COUNT_PATTERN.pattern,
+            "target_scenes_pattern": _TARGET_SCENES_PATTERN.pattern,
+            "scene_count_range": [_MIN_SCENE_COUNT, _MAX_SCENE_COUNT],
+            "story_boundary": CHAT_STORY_BOUNDARY,
+            "rendered_output_contracts": {
+                str(scene_count): _render_output_contract(scene_count)
+                for scene_count in range(_MIN_SCENE_COUNT, _MAX_SCENE_COUNT + 1)
+            },
+        },
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def smollm3_render_output_contract(scene_count: int) -> str:
+    """Render the exact SmolLM3 v5 output contract used for SFT."""
+
+    if not _MIN_SCENE_COUNT <= scene_count <= _MAX_SCENE_COUNT:
+        raise ValueError("v4 scene count must be between 1 and 6")
+    headings = ", ".join(
+        f"`### Scene {index:02d}:`"
+        for index in range(1, scene_count + 1)
+    )
+    minimum, maximum = SMOLLM3_SCENE_WORD_RANGE
+    return (
+        "Output contract (follow exactly):\n"
+        f"- Use these scene prefixes in order: {headings}.\n"
+        f"- Write exactly {scene_count} scenes and {minimum}-{maximum} words per scene.\n"
+        "- Use no heading except those scene headings.\n"
+        "- Copy every item on `Must include` verbatim into the story.\n"
+        "- Show the character-role details through decisions, action, or dialogue.\n"
+        f"- Resolve the ending target in Scene {scene_count:02d} and stop.\n\n"
+    )
+
+
+def _canonical_smollm3_scene_count(prompt: str) -> int:
+    scene_counts = _SCENE_COUNT_PATTERN.findall(prompt)
+    target_counts = _TARGET_SCENES_PATTERN.findall(prompt)
+    if len(scene_counts) != 1 or len(target_counts) != 1:
+        raise ValueError("v4 prompt needs one Scene Count and one Target scenes line")
+    scene_count = int(scene_counts[0])
+    target_count = int(target_counts[0])
+    if not _MIN_SCENE_COUNT <= scene_count <= _MAX_SCENE_COUNT:
+        raise ValueError("v4 scene count must be between 1 and 6")
+    if scene_count != target_count:
+        raise ValueError("v4 Scene Count and Target scenes must match")
+    return scene_count
+
+
+def smollm3_transform_prompt(prompt: str) -> str:
+    """Apply the exact SmolLM3 v5 prompt transform used for SFT."""
+
+    scene_count = _canonical_smollm3_scene_count(prompt)
+    if not prompt.endswith(SMOLLM3_STORY_BOUNDARY):
+        raise ValueError("v4 prompt must end at the canonical Story boundary")
+    return (
+        prompt[: -len(SMOLLM3_STORY_BOUNDARY)]
+        + smollm3_render_output_contract(scene_count)
+        + SMOLLM3_STORY_BOUNDARY
+    )
+
+
+def smollm3_chat_messages(
+    prompt: str,
+    completion: str | None = None,
+) -> list[dict[str, str]]:
+    messages = [
+        {"role": "system", "content": SMOLLM3_SYSTEM_PROMPT},
+        {"role": "user", "content": smollm3_transform_prompt(prompt)},
+    ]
+    if completion is not None:
+        messages.append({"role": "assistant", "content": completion})
+    return messages
+
+
+def smollm3_prompt_contract_sha256() -> str:
+    """Hash the exact SmolLM3 v5 prompt contract used for SFT."""
+
+    payload = {
+        "format": SMOLLM3_CHAT_PROMPT_FORMAT,
+        "system": SMOLLM3_SYSTEM_PROMPT,
+        "messages": ["system", "user", "assistant"],
+        "assistant_only_loss": True,
+        "thinking": False,
+        "context_length": SMOLLM3_PRODUCT_CONTEXT_LENGTH,
+        "transform_version": SMOLLM3_PROMPT_TRANSFORM_VERSION,
+        "story_boundary": SMOLLM3_STORY_BOUNDARY,
+        "scene_count_pattern": _SCENE_COUNT_PATTERN.pattern,
+        "target_scenes_pattern": _TARGET_SCENES_PATTERN.pattern,
+        "scene_word_range": list(SMOLLM3_SCENE_WORD_RANGE),
+        "rendered_contracts": {
+            str(count): smollm3_render_output_contract(count)
+            for count in range(_MIN_SCENE_COUNT, _MAX_SCENE_COUNT + 1)
+        },
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def raw_prompt_contract_sha256() -> str:
+    payload = {
+        "format": RAW_PROMPT_FORMAT,
+        "messages": ["raw-markdown-prompt"],
+        "bos_prefix": True,
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def product_context_length_for_prompt_format(prompt_format: str) -> int | None:
+    if prompt_format == CHAT_PROMPT_FORMAT:
+        return PRODUCT_CONTEXT_LENGTH
+    if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT:
+        return SMOLLM3_PRODUCT_CONTEXT_LENGTH
+    if prompt_format == RAW_PROMPT_FORMAT:
+        return None
+    raise ValueError(f"unsupported prompt format: {prompt_format}")
+
+
+def _has_model_weights(root: Path) -> bool:
+    return (root / "model.safetensors").is_file() or (
+        root / "model.safetensors.index.json"
+    ).is_file()
+
+
+def validate_transformers_artifact(root: Path) -> tuple[Mapping[str, Any], str]:
+    """Validate either the legacy custom export or a standard Transformers LM."""
+
+    missing = [name for name in COMMON_ARTIFACT_FILES if not (root / name).is_file()]
+    if missing:
+        raise ValueError("model repository is missing: " + ", ".join(missing))
+    if not _has_model_weights(root):
+        raise ValueError("model repository is missing Safetensors weights")
+    try:
+        config = json.loads((root / "config.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"could not read config.json: {exc}") from exc
+    if not isinstance(config, Mapping):
+        raise ValueError("config.json must contain a JSON object")
+    auto_map = config.get("auto_map")
+    if isinstance(auto_map, Mapping) and auto_map.get("AutoModelForCausalLM"):
+        missing_code = [name for name in CUSTOM_CODE_FILES if not (root / name).is_file()]
+        if missing_code:
+            raise ValueError("custom model repository is missing: " + ", ".join(missing_code))
+        return config, "custom"
+    architectures = config.get("architectures")
+    if not isinstance(architectures, list) or not all(
+        isinstance(value, str) and value for value in architectures
+    ):
+        raise ValueError("standard model config needs a non-empty architectures list")
+    if not isinstance(config.get("model_type"), str) or not config["model_type"]:
+        raise ValueError("standard model config needs model_type")
+    return config, "standard"
+
+
+def _expected_prompt_contract_sha256(prompt_format: str) -> str:
+    if prompt_format == CHAT_PROMPT_FORMAT:
+        return prompt_contract_sha256()
+    if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT:
+        return smollm3_prompt_contract_sha256()
+    if prompt_format == RAW_PROMPT_FORMAT:
+        return raw_prompt_contract_sha256()
+    raise ValueError(f"unsupported prompt format: {prompt_format}")
+
+
+def _manifest_prompt_binding(
+    manifest: Mapping[str, Any],
+    *,
+    artifact_kind: str,
+) -> tuple[str, str] | None:
+    """Read legacy top-level or SmolLM3 nested bindings without ambiguity."""
+
+    top_format_present = "prompt_format" in manifest
+    top_hash_present = "prompt_contract_sha256" in manifest
+    nested_present = "prompt_contract" in manifest
+    if not top_format_present and not top_hash_present and not nested_present:
+        if artifact_kind == "custom":
+            return None
+        raise ValueError("training manifest has no supported prompt_format")
+    if top_format_present != top_hash_present:
+        raise ValueError("training manifest prompt binding is incomplete")
+
+    bindings: list[tuple[str, str]] = []
+    if top_format_present:
+        bindings.append(
+            (manifest.get("prompt_format"), manifest.get("prompt_contract_sha256"))
+        )
+    if nested_present:
+        nested = manifest.get("prompt_contract")
+        if (
+            not isinstance(nested, Mapping)
+            or set(nested) != {"format", "sha256", "thinking"}
+            or nested.get("thinking") is not False
+        ):
+            raise ValueError("training manifest nested prompt contract is invalid")
+        bindings.append((nested.get("format"), nested.get("sha256")))
+    if any(
+        not isinstance(value, str)
+        or not value
+        or not isinstance(digest, str)
+        or re.fullmatch(r"[0-9a-f]{64}", digest) is None
+        for value, digest in bindings
+    ):
+        raise ValueError("training manifest prompt binding is invalid")
+    if any(binding != bindings[0] for binding in bindings[1:]):
+        raise ValueError("training manifest prompt bindings conflict")
+    return bindings[0]
+
+
+def prompt_format_for_artifact(root: Path, artifact_kind: str, tokenizer: Any) -> str:
+    manifest_path = root / "training_manifest.json"
+    if manifest_path.is_file():
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if not isinstance(manifest, Mapping):
+            raise ValueError("training manifest must contain a JSON object")
+        binding = _manifest_prompt_binding(manifest, artifact_kind=artifact_kind)
+        if binding is None:
+            # Checked-in pre-contract SmolGPT exports are unambiguously the raw
+            # Markdown/BOS path. Any partially declared contract still fails.
+            return RAW_PROMPT_FORMAT
+        value, contract_hash = binding
+        if value not in SUPPORTED_PROMPT_FORMATS:
+            raise ValueError("training manifest has no supported prompt_format")
+        if artifact_kind == "standard" and value not in CHAT_PROMPT_FORMATS:
+            raise ValueError("standard product manifest must use the chat prompt format")
+        if artifact_kind == "custom" and value == SMOLLM3_CHAT_PROMPT_FORMAT:
+            raise ValueError("SmolLM3 chat-v5 requires a standard model artifact")
+        expected_sha = _expected_prompt_contract_sha256(value)
+        if contract_hash != expected_sha:
+            raise ValueError("training manifest prompt contract hash does not match runtime")
+        if value in CHAT_PROMPT_FORMATS and not getattr(
+            tokenizer, "chat_template", None
+        ):
+            raise ValueError("chat prompt format requires a tokenizer chat_template")
+        return str(value)
+    if artifact_kind == "standard" and getattr(tokenizer, "chat_template", None):
+        return CHAT_PROMPT_FORMAT
+    return RAW_PROMPT_FORMAT
+
+
+def _canonical_scene_count(prompt: str) -> int:
+    scene_counts = _SCENE_COUNT_PATTERN.findall(prompt)
+    target_counts = _TARGET_SCENES_PATTERN.findall(prompt)
+    if len(scene_counts) != 1:
+        raise ValueError(
+            "chat-v3 prompt must contain exactly one canonical '- Scene Count: N' line"
+        )
+    if len(target_counts) != 1:
+        raise ValueError(
+            "chat-v3 prompt must contain exactly one canonical '- Target scenes: N' line"
+        )
+    scene_count = int(scene_counts[0])
+    target_count = int(target_counts[0])
+    if not _MIN_SCENE_COUNT <= scene_count <= _MAX_SCENE_COUNT:
+        raise ValueError("chat-v3 Scene Count must be between 1 and 6")
+    if not _MIN_SCENE_COUNT <= target_count <= _MAX_SCENE_COUNT:
+        raise ValueError("chat-v3 Target scenes must be between 1 and 6")
+    if scene_count != target_count:
+        raise ValueError("chat-v3 Scene Count and Target scenes must match")
+    return scene_count
+
+
+def _transform_chat_prompt(prompt: str) -> str:
+    scene_count = _canonical_scene_count(prompt)
+    if not prompt.endswith(CHAT_STORY_BOUNDARY):
+        raise ValueError("chat-v3 prompt must end at the canonical '## Story' boundary")
+    return (
+        prompt[: -len(CHAT_STORY_BOUNDARY)]
+        + _render_output_contract(scene_count)
+        + CHAT_STORY_BOUNDARY
+    )
+
+
+def chat_messages(prompt: str, completion: str | None = None) -> list[dict[str, str]]:
+    messages = [
+        {"role": "system", "content": CHAT_SYSTEM_PROMPT},
+        {"role": "user", "content": _transform_chat_prompt(prompt)},
+    ]
+    if completion is not None:
+        messages.append({"role": "assistant", "content": completion})
+    return messages
+
+
+def _chat_messages_for_format(
+    prompt: str,
+    completion: str | None,
+    prompt_format: str,
+) -> list[dict[str, str]]:
+    if prompt_format == CHAT_PROMPT_FORMAT:
+        return chat_messages(prompt, completion)
+    if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT:
+        return smollm3_chat_messages(prompt, completion)
+    raise ValueError(f"unsupported chat prompt format: {prompt_format}")
+
+
+def _apply_runtime_chat_template(
+    tokenizer: Any,
+    messages: list[dict[str, str]],
+    *,
+    prompt_format: str,
+    add_generation_prompt: bool,
+) -> Any:
+    kwargs: dict[str, Any] = {
+        "add_generation_prompt": add_generation_prompt,
+        "tokenize": True,
+    }
+    if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT:
+        kwargs["enable_thinking"] = False
+    return tokenizer.apply_chat_template(messages, **kwargs)
+
+
+def _flatten_token_ids(values: Any, *, context: str) -> list[int]:
+    """Normalize chat-template outputs across supported Transformers versions."""
+
+    if isinstance(values, Mapping):
+        if "input_ids" not in values:
+            raise ValueError(f"{context} returned no input_ids")
+        values = values["input_ids"]
+    if hasattr(values, "tolist"):
+        values = values.tolist()
+    if not isinstance(values, Sequence) or isinstance(values, (str, bytes, bytearray)):
+        raise ValueError(f"{context} returned unsupported token IDs")
+    normalized = list(values)
+    if normalized and isinstance(normalized[0], Sequence) and not isinstance(
+        normalized[0], (str, bytes, bytearray)
+    ):
+        if len(normalized) != 1:
+            raise ValueError(f"{context} returned more than one token sequence")
+        normalized = list(normalized[0])
+    try:
+        return [int(value) for value in normalized]
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{context} returned non-integer token IDs") from exc
+
+
+def generation_prompt_ids(tokenizer: Any, prompt: str, prompt_format: str) -> list[int]:
+    if prompt_format in CHAT_PROMPT_FORMATS:
+        values = _apply_runtime_chat_template(
+            tokenizer,
+            _chat_messages_for_format(prompt, None, prompt_format),
+            prompt_format=prompt_format,
+            add_generation_prompt=True,
+        )
+        context = (
+            "SmolLM3 v5 generation template"
+            if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT
+            else "chat generation template"
+        )
+        return _flatten_token_ids(values, context=context)
+    if prompt_format != RAW_PROMPT_FORMAT:
+        raise ValueError(f"unsupported prompt format: {prompt_format}")
+    return [
+        int(tokenizer.bos_token_id),
+        *(
+            int(value)
+            for value in tokenizer.encode(prompt, add_special_tokens=False)
+        ),
+    ]
+
+
+def assistant_training_ids(
+    tokenizer: Any,
+    prompt: str,
+    completion: str,
+    *,
+    max_length: int,
+    prompt_format: str = CHAT_PROMPT_FORMAT,
+) -> tuple[list[int], list[int]]:
+    """Create one chat sequence with loss masked through the assistant header."""
+
+    if prompt_format not in CHAT_PROMPT_FORMATS:
+        raise ValueError("assistant training requires a supported chat prompt format")
+    prefix = generation_prompt_ids(tokenizer, prompt, prompt_format)
+    full = _flatten_token_ids(
+        _apply_runtime_chat_template(
+            tokenizer,
+            _chat_messages_for_format(prompt, completion, prompt_format),
+            prompt_format=prompt_format,
+            add_generation_prompt=False,
+        ),
+        context=(
+            "SmolLM3 v5 training template"
+            if prompt_format == SMOLLM3_CHAT_PROMPT_FORMAT
+            else "chat training template"
+        ),
+    )
+    if full[: len(prefix)] != prefix:
+        raise ValueError("chat template assistant prefix is not stable")
+    if len(full) > max_length:
+        raise ValueError(
+            f"chat-formatted example has {len(full)} tokens; maximum is {max_length}"
+        )
+    if len(full) <= len(prefix):
+        raise ValueError("chat-formatted example has no assistant completion tokens")
+    labels = [-100] * len(prefix) + full[len(prefix) :]
+    return full, labels
+
+
+def aggregate_sha256(paths: Sequence[Path], root: Path) -> str:
+    records = []
+    for path in sorted(paths):
+        records.append(
+            {
+                "path": path.relative_to(root).as_posix(),
+                "sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+            }
+        )
+    payload = json.dumps(records, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(payload).hexdigest()

tests/test_runtime_contract_v3.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+SPACE_DIR = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SPACE_DIR))
+
+import runtime_contract as contract  # noqa: E402
+
+
+def canonical_prompt(scene_count: int = 3) -> str:
+    return (
+        "# Story: Contract Test\n\n"
+        "## Metadata\n\n"
+        f"- Scene Count: {scene_count}\n\n"
+        "## Canvas\n\n"
+        "### Constraints\n\n"
+        f"- Target scenes: {scene_count}\n"
+        "- Must include: Mara, moonbell.\n\n"
+        "### Ending Target\n\n"
+        "Mara rings the moonbell.\n\n"
+        "## Story\n\n"
+    )
+
+
+class RecordingChatTokenizer:
+    bos_token_id = 1
+
+    def __init__(self) -> None:
+        self.message_calls: list[list[dict[str, str]]] = []
+        self.raw_encode_calls: list[str] = []
+
+    @staticmethod
+    def _encode(value: str) -> list[int]:
+        return [ord(character) for character in value]
+
+    def apply_chat_template(
+        self,
+        messages,
+        *,
+        add_generation_prompt,
+        tokenize,
+    ):
+        assert tokenize
+        copied = [dict(message) for message in messages]
+        self.message_calls.append(copied)
+        rendered = "".join(
+            f"<{message['role']}>{message['content']}" for message in copied
+        )
+        if add_generation_prompt:
+            rendered += "<assistant>"
+        else:
+            rendered += "<end>"
+        return self._encode(rendered)
+
+    def encode(self, value, add_special_tokens=False):
+        assert not add_special_tokens
+        self.raw_encode_calls.append(value)
+        return self._encode(value)
+
+
+class ChatV3ContractTests(unittest.TestCase):
+    def test_format_and_system_allow_only_consecutive_scene_h3_headings(self) -> None:
+        self.assertEqual(contract.CHAT_PROMPT_FORMAT, "smolgpt-fables-chat-v3")
+        self.assertIn("zero-padded `### Scene NN:`", contract.CHAT_SYSTEM_PROMPT)
+        self.assertIn("only headings allowed", contract.CHAT_SYSTEM_PROMPT)
+        self.assertIn("never emit an H1, H2", contract.CHAT_SYSTEM_PROMPT)
+        self.assertIn("any other H3", contract.CHAT_SYSTEM_PROMPT)
+        self.assertIn("H4 or deeper", contract.CHAT_SYSTEM_PROMPT)
+        self.assertIn("Stop immediately after", contract.CHAT_SYSTEM_PROMPT)
+
+    def test_chat_prompt_injects_the_exact_count_specific_contract_at_boundary(self) -> None:
+        prompt = canonical_prompt(3)
+        transformed = contract.chat_messages(prompt)[1]["content"]
+        expected_contract = (
+            "Output contract (follow exactly): use only these H3 heading prefixes, "
+            "in this order: `### Scene 01:`, `### Scene 02:`, `### Scene 03:`. "
+            "Write exactly 3 scenes; emit no other heading or section; stop "
+            "immediately after completing `### Scene 03:`.\n\n"
+        )
+        self.assertEqual(
+            transformed,
+            prompt[: -len(contract.CHAT_STORY_BOUNDARY)]
+            + expected_contract
+            + contract.CHAT_STORY_BOUNDARY,
+        )
+        self.assertEqual(transformed.count(expected_contract), 1)
+        self.assertTrue(transformed.endswith(expected_contract + "## Story\n\n"))
+
+    def test_generation_and_training_use_the_identical_central_transform(self) -> None:
+        tokenizer = RecordingChatTokenizer()
+        prompt = canonical_prompt(4)
+        contract.generation_prompt_ids(tokenizer, prompt, contract.CHAT_PROMPT_FORMAT)
+        contract.assistant_training_ids(
+            tokenizer,
+            prompt,
+            "### Scene 01: Start\n\nMara listened.\n",
+            max_length=10_000,
+        )
+        transformed_prompts = [call[1]["content"] for call in tokenizer.message_calls]
+        self.assertEqual(len(transformed_prompts), 3)
+        self.assertEqual(len(set(transformed_prompts)), 1)
+        self.assertIn("`### Scene 04:`", transformed_prompts[0])
+        self.assertNotIn("`### Scene 05:`", transformed_prompts[0])
+
+    def test_raw_legacy_generation_does_not_apply_chat_transform(self) -> None:
+        tokenizer = RecordingChatTokenizer()
+        raw_prompt = "legacy prompt without scene metadata"
+        values = contract.generation_prompt_ids(
+            tokenizer,
+            raw_prompt,
+            contract.RAW_PROMPT_FORMAT,
+        )
+        self.assertEqual(values, [tokenizer.bos_token_id, *tokenizer._encode(raw_prompt)])
+        self.assertEqual(tokenizer.raw_encode_calls, [raw_prompt])
+        self.assertEqual(tokenizer.message_calls, [])
+
+    def test_scene_count_metadata_and_story_boundary_fail_closed(self) -> None:
+        prompt = canonical_prompt(3)
+        invalid_prompts = {
+            "missing Scene Count": prompt.replace("- Scene Count: 3\n\n", "", 1),
+            "missing Target scenes": prompt.replace("- Target scenes: 3\n", "", 1),
+            "mismatched counts": prompt.replace("- Target scenes: 3", "- Target scenes: 2"),
+            "Scene Count below range": prompt.replace("- Scene Count: 3", "- Scene Count: 0"),
+            "Target scenes above range": prompt.replace(
+                "- Target scenes: 3", "- Target scenes: 7"
+            ),
+            "duplicate Scene Count": prompt.replace(
+                "- Scene Count: 3", "- Scene Count: 3\n- Scene Count: 3"
+            ),
+            "noncanonical boundary": prompt.rstrip("\n"),
+        }
+        for label, invalid in invalid_prompts.items():
+            with self.subTest(label=label), self.assertRaises(ValueError):
+                contract.chat_messages(invalid)
+
+    def test_prompt_hash_binds_transform_version_and_rendered_content(self) -> None:
+        baseline = contract.prompt_contract_sha256()
+        with mock.patch.object(
+            contract,
+            "CHAT_PROMPT_TRANSFORM_VERSION",
+            "scene-output-contract-test-version",
+        ):
+            self.assertNotEqual(contract.prompt_contract_sha256(), baseline)
+        with mock.patch.object(
+            contract,
+            "CHAT_OUTPUT_CONTRACT_TEMPLATE",
+            contract.CHAT_OUTPUT_CONTRACT_TEMPLATE + "test-content",
+        ):
+            self.assertNotEqual(contract.prompt_contract_sha256(), baseline)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_runtime_contract_v5.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+
+
+SPACE_DIR = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[3]
+for path in (SPACE_DIR, ROOT / "src"):
+    if str(path) not in sys.path:
+        sys.path.insert(0, str(path))
+
+import runtime_contract as runtime  # noqa: E402
+from smolgpt import smollm3_contract as source  # noqa: E402
+
+
+def canonical_prompt(scene_count: int = 3) -> str:
+    return (
+        "# Story: Contract Test\n\n"
+        "## Metadata\n\n"
+        f"- Scene Count: {scene_count}\n\n"
+        "## Canvas\n\n"
+        "### Constraints\n\n"
+        f"- Target scenes: {scene_count}\n"
+        "- Must include: Mara, moonbell.\n\n"
+        "### Ending Target\n\n"
+        "Mara rings the moonbell.\n\n"
+        "## Story\n\n"
+    )
+
+
+class SmolLM3Tokenizer:
+    bos_token_id = 1
+    chat_template = "pinned-smollm3-template"
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[list[dict[str, str]], dict[str, object]]] = []
+
+    def apply_chat_template(self, messages, **kwargs):
+        copied = [dict(message) for message in messages]
+        self.calls.append((copied, dict(kwargs)))
+        if kwargs["add_generation_prompt"]:
+            return [10, 11, 12]
+        return [10, 11, 12, 20, 21]
+
+
+class SmolLM3RuntimeContractTests(unittest.TestCase):
+    def test_v5_runtime_contract_is_byte_equivalent_to_source_contract(self) -> None:
+        self.assertEqual(runtime.SMOLLM3_CHAT_PROMPT_FORMAT, source.CHAT_PROMPT_FORMAT)
+        self.assertEqual(runtime.SMOLLM3_SYSTEM_PROMPT, source.SYSTEM_PROMPT)
+        self.assertEqual(
+            runtime.SMOLLM3_PROMPT_TRANSFORM_VERSION,
+            source.PROMPT_TRANSFORM_VERSION,
+        )
+        self.assertEqual(runtime.SMOLLM3_STORY_BOUNDARY, source.STORY_BOUNDARY)
+        self.assertEqual(runtime.SMOLLM3_SCENE_WORD_RANGE, source.SCENE_WORD_RANGE)
+        self.assertEqual(
+            runtime.SMOLLM3_PRODUCT_CONTEXT_LENGTH,
+            source.PRODUCT_CONTEXT_LENGTH,
+        )
+        self.assertEqual(
+            runtime.smollm3_prompt_contract_sha256(),
+            source.prompt_contract_sha256(),
+        )
+        completion = "### Scene 01:\n\nMara rang the moonbell."
+        for scene_count in range(1, 7):
+            prompt = canonical_prompt(scene_count)
+            self.assertEqual(
+                runtime.smollm3_render_output_contract(scene_count),
+                source.render_output_contract(scene_count),
+            )
+            self.assertEqual(
+                runtime.smollm3_transform_prompt(prompt),
+                source.transform_prompt(prompt),
+            )
+            self.assertEqual(
+                runtime.smollm3_chat_messages(prompt),
+                source.chat_messages(prompt),
+            )
+            self.assertEqual(
+                runtime.smollm3_chat_messages(prompt, completion),
+                source.chat_messages(prompt, completion),
+            )
+
+    def test_v5_generation_and_training_tokenization_match_source_exactly(self) -> None:
+        prompt = canonical_prompt(2)
+        completion = "### Scene 01:\n\nMara listened."
+        source_tokenizer = SmolLM3Tokenizer()
+        runtime_tokenizer = SmolLM3Tokenizer()
+
+        source_generation = source.generation_prompt_ids(source_tokenizer, prompt)
+        runtime_generation = runtime.generation_prompt_ids(
+            runtime_tokenizer,
+            prompt,
+            runtime.SMOLLM3_CHAT_PROMPT_FORMAT,
+        )
+        self.assertEqual(runtime_generation, source_generation)
+        self.assertEqual(runtime_tokenizer.calls, source_tokenizer.calls)
+        self.assertFalse(runtime_tokenizer.calls[0][1]["enable_thinking"])
+
+        source_training = source.assistant_training_ids(
+            source_tokenizer,
+            prompt,
+            completion,
+        )
+        runtime_training = runtime.assistant_training_ids(
+            runtime_tokenizer,
+            prompt,
+            completion,
+            max_length=runtime.SMOLLM3_PRODUCT_CONTEXT_LENGTH,
+            prompt_format=runtime.SMOLLM3_CHAT_PROMPT_FORMAT,
+        )
+        self.assertEqual(runtime_training, source_training)
+        self.assertEqual(runtime_tokenizer.calls, source_tokenizer.calls)
+        self.assertTrue(
+            all(call[1]["enable_thinking"] is False for call in runtime_tokenizer.calls)
+        )
+
+    def test_v5_transform_fails_closed_on_every_source_rejected_shape(self) -> None:
+        prompt = canonical_prompt(3)
+        invalid = (
+            prompt.replace("- Scene Count: 3\n\n", "", 1),
+            prompt.replace("- Target scenes: 3\n", "", 1),
+            prompt.replace("- Target scenes: 3", "- Target scenes: 2"),
+            prompt.replace("- Scene Count: 3", "- Scene Count: 7"),
+            prompt.replace("- Scene Count: 3", "- Scene Count: 3\n- Scene Count: 3"),
+            prompt.rstrip("\n"),
+        )
+        for value in invalid:
+            with self.subTest(prompt=value[-80:]):
+                with self.assertRaises(ValueError):
+                    source.transform_prompt(value)
+                with self.assertRaises(ValueError):
+                    runtime.smollm3_transform_prompt(value)
+
+    def test_v5_manifest_accepts_exact_top_level_or_nested_binding(self) -> None:
+        tokenizer = SmolLM3Tokenizer()
+        digest = source.prompt_contract_sha256()
+        manifests = (
+            {
+                "prompt_format": source.CHAT_PROMPT_FORMAT,
+                "prompt_contract_sha256": digest,
+            },
+            {
+                "prompt_contract": {
+                    "format": source.CHAT_PROMPT_FORMAT,
+                    "sha256": digest,
+                    "thinking": False,
+                }
+            },
+            {
+                "prompt_format": source.CHAT_PROMPT_FORMAT,
+                "prompt_contract_sha256": digest,
+                "prompt_contract": {
+                    "format": source.CHAT_PROMPT_FORMAT,
+                    "sha256": digest,
+                    "thinking": False,
+                },
+            },
+        )
+        for manifest in manifests:
+            with self.subTest(manifest=manifest), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                (root / "training_manifest.json").write_text(
+                    json.dumps(manifest), encoding="utf-8"
+                )
+                self.assertEqual(
+                    runtime.prompt_format_for_artifact(root, "standard", tokenizer),
+                    runtime.SMOLLM3_CHAT_PROMPT_FORMAT,
+                )
+
+    def test_v5_manifest_rejects_ambiguous_or_incompatible_bindings(self) -> None:
+        digest = source.prompt_contract_sha256()
+        invalid = {
+            "wrong hash": {
+                "prompt_format": source.CHAT_PROMPT_FORMAT,
+                "prompt_contract_sha256": "0" * 64,
+            },
+            "partial top-level": {"prompt_format": source.CHAT_PROMPT_FORMAT},
+            "thinking enabled": {
+                "prompt_contract": {
+                    "format": source.CHAT_PROMPT_FORMAT,
+                    "sha256": digest,
+                    "thinking": True,
+                }
+            },
+            "nested extra field": {
+                "prompt_contract": {
+                    "format": source.CHAT_PROMPT_FORMAT,
+                    "sha256": digest,
+                    "thinking": False,
+                    "extra": "unreviewed",
+                }
+            },
+            "conflicting bindings": {
+                "prompt_format": source.CHAT_PROMPT_FORMAT,
+                "prompt_contract_sha256": digest,
+                "prompt_contract": {
+                    "format": runtime.CHAT_PROMPT_FORMAT,
+                    "sha256": runtime.prompt_contract_sha256(),
+                    "thinking": False,
+                },
+            },
+        }
+        for label, manifest in invalid.items():
+            with self.subTest(label=label), tempfile.TemporaryDirectory() as directory:
+                root = Path(directory)
+                (root / "training_manifest.json").write_text(
+                    json.dumps(manifest), encoding="utf-8"
+                )
+                with self.assertRaises(ValueError):
+                    runtime.prompt_format_for_artifact(
+                        root,
+                        "standard",
+                        SmolLM3Tokenizer(),
+                    )
+
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "training_manifest.json").write_text(
+                json.dumps(
+                    {
+                        "prompt_format": source.CHAT_PROMPT_FORMAT,
+                        "prompt_contract_sha256": digest,
+                    }
+                ),
+                encoding="utf-8",
+            )
+            with self.assertRaisesRegex(ValueError, "standard model artifact"):
+                runtime.prompt_format_for_artifact(
+                    root,
+                    "custom",
+                    SmolLM3Tokenizer(),
+                )
+            with self.assertRaisesRegex(ValueError, "chat_template"):
+                runtime.prompt_format_for_artifact(
+                    root,
+                    "standard",
+                    SimpleNamespace(chat_template=None),
+                )
+
+    def test_context_length_is_versioned_without_changing_legacy_paths(self) -> None:
+        self.assertEqual(
+            runtime.product_context_length_for_prompt_format(
+                runtime.SMOLLM3_CHAT_PROMPT_FORMAT
+            ),
+            4096,
+        )
+        self.assertEqual(
+            runtime.product_context_length_for_prompt_format(
+                runtime.CHAT_PROMPT_FORMAT
+            ),
+            2048,
+        )
+        self.assertIsNone(
+            runtime.product_context_length_for_prompt_format(
+                runtime.RAW_PROMPT_FORMAT
+            )
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_space.py

@@ -15,6 +15,7 @@ SPACE_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(SPACE_DIR))
 
 import app  # noqa: E402
+import runtime_contract as contract  # noqa: E402
 
 
 class RecordingProgress:
@@ -74,6 +75,56 @@ class DeterministicCausalModel:
         return SimpleNamespace(logits=logits, past_key_values=cache)
 
 
+class PromptCopyModel:
+    """Prefer a prompt token first, then expose generated-only repetition control."""
+
+    def __init__(self) -> None:
+        self.config = SimpleNamespace(context_length=32)
+
+    def __call__(self, input_ids, past_key_values=None, use_cache=False, **kwargs):
+        del past_key_values, use_cache, kwargs
+        logits = app.torch.full(
+            (input_ids.shape[0], input_ids.shape[1], 256),
+            -10.0,
+            device=input_ids.device,
+        )
+        logits[:, :, ord("z")] = 10.0
+        logits[:, :, ord("y")] = 9.0
+        return SimpleNamespace(logits=logits, past_key_values=None)
+
+
+class TokenSequenceModel:
+    def __init__(self, context_length: int, values) -> None:
+        self.config = SimpleNamespace(context_length=context_length)
+        self.values = list(values)
+        self.calls = 0
+
+    def __call__(self, input_ids, past_key_values=None, use_cache=False, **kwargs):
+        del past_key_values, use_cache, kwargs
+        value = self.values[min(self.calls, len(self.values) - 1)]
+        self.calls += 1
+        logits = app.torch.full(
+            (input_ids.shape[0], input_ids.shape[1], 256),
+            -10.0,
+            device=input_ids.device,
+        )
+        logits[:, :, int(value)] = 10.0
+        return SimpleNamespace(logits=logits, past_key_values=None)
+
+
+class LossyDecodeTokenizer(CharacterTokenizer):
+    def __init__(self) -> None:
+        self.encode_calls = []
+
+    def encode(self, text, add_special_tokens=False, **kwargs):
+        self.encode_calls.append(text)
+        return super().encode(text, add_special_tokens=add_special_tokens, **kwargs)
+
+    def decode(self, token_ids, skip_special_tokens=True, **kwargs):
+        del token_ids, skip_special_tokens, kwargs
+        return "collapsed-decoding"
+
+
 class ContinuationCacheTests(unittest.TestCase):
     @staticmethod
     def bundle(model):
@@ -134,6 +185,76 @@ class ContinuationCacheTests(unittest.TestCase):
         self.assertEqual(result, "zz")
         self.assertEqual(model.call_lengths, [prompt_length, 1])
 
+    def test_repetition_penalty_ignores_prompt_but_penalizes_generated_tokens(self) -> None:
+        result = app.generate_continuation(
+            self.bundle(PromptCopyModel()),
+            "z",
+            temperature=0.0,
+            top_p=1.0,
+            top_k=0,
+            repetition_penalty=2.0,
+            max_new_tokens=2,
+        )
+        self.assertEqual(result, "zy")
+
+    def test_trace_records_context_clamp_and_exact_budget_stop(self) -> None:
+        prompt = "small harbor"
+        prompt_length = 1 + len(prompt)
+        model = DeterministicCausalModel(prompt_length + 2, returns_cache=True)
+        result = app.generate_continuation_with_trace(
+            self.bundle(model),
+            prompt,
+            temperature=0.0,
+            top_p=1.0,
+            top_k=0,
+            repetition_penalty=1.0,
+            max_new_tokens=12,
+        )
+        self.assertEqual(result.continuation, "zz")
+        self.assertEqual(result.trace.requested_token_budget, 12)
+        self.assertEqual(result.trace.effective_token_budget, 2)
+        self.assertEqual(result.trace.emitted_continuation_token_count, 2)
+        self.assertEqual(result.trace.stop_reason, "token-budget")
+
+    def test_trace_classifies_eos_without_counting_eos_as_continuation(self) -> None:
+        prompt = "small harbor"
+        model = TokenSequenceModel(100, [ord("z"), CharacterTokenizer.eos_token_id])
+        result = app.generate_continuation_with_trace(
+            self.bundle(model),
+            prompt,
+            temperature=0.0,
+            top_p=1.0,
+            top_k=0,
+            repetition_penalty=1.0,
+            max_new_tokens=5,
+        )
+        self.assertEqual(result.continuation, "z")
+        self.assertEqual(result.trace.requested_token_budget, 5)
+        self.assertEqual(result.trace.effective_token_budget, 5)
+        self.assertEqual(result.trace.emitted_continuation_token_count, 1)
+        self.assertEqual(result.trace.stop_reason, "eos")
+
+    def test_trace_counts_generated_ids_before_lossy_decode_without_reencoding(self) -> None:
+        tokenizer = LossyDecodeTokenizer()
+        bundle = SimpleNamespace(
+            tokenizer=tokenizer,
+            model=DeterministicCausalModel(20, returns_cache=True),
+            device=app.torch.device("cpu"),
+        )
+        result = app.generate_continuation_with_trace(
+            bundle,
+            "p",
+            temperature=0.0,
+            top_p=1.0,
+            top_k=0,
+            repetition_penalty=1.0,
+            max_new_tokens=3,
+        )
+        self.assertEqual(result.continuation, "collapsed-decoding")
+        self.assertEqual(result.trace.emitted_continuation_token_count, 3)
+        self.assertEqual(result.trace.stop_reason, "token-budget")
+        self.assertEqual(tokenizer.encode_calls, ["p"])
+
 
 class CanvasTests(unittest.TestCase):
     def test_canvas_matches_story_schema_boundary(self) -> None:
@@ -222,7 +343,9 @@ class StudioPresentationTests(unittest.TestCase):
         )
         self.assertEqual(canvas, story_input)
         self.assertEqual(tokens, app.SCENE_TOKEN_BUDGETS[3])
-        self.assertIn("# Canvas: Mara and Ilyan", canvas)
+        self.assertIn(
+            "# Canvas: Star visible only at dawn at winter observatory", canvas
+        )
         self.assertIn("- Tags: high-fantasy, close-third-person", canvas)
         self.assertIn("- Scene Count: 3", canvas)
         self.assertIn("#### Mara\n- Role: a careful mapmaker and protagonist", canvas)
@@ -248,7 +371,7 @@ class StudioPresentationTests(unittest.TestCase):
         )
 
     def test_novel_studio_brief_uses_the_trained_anchor_contract(self) -> None:
-        canvas, _, _ = app.prepare_story(
+        canvas, _, _ = app.prepare_studio_story(
             "A young fox named Nilo must return a stolen moonbell to the "
             "lighthouse before the first winter tide.",
             "Cozy fantasy",
@@ -262,14 +385,148 @@ class StudioPresentationTests(unittest.TestCase):
             "Include a red wool scarf\nAvoid a tragic ending",
             None,
         )
-        self.assertTrue(canvas.startswith("# Canvas: Nilo and Mara\n"))
+        self.assertTrue(
+            canvas.startswith(
+                "# Canvas: Red wool scarf at wind-carved island village during the first snow\n"
+            )
+        )
         must_include = next(
             line for line in canvas.splitlines() if line.startswith("- Must include:")
         )
-        for anchor in ("Nilo", "Mara", "moonbell", "lighthouse", "red wool scarf"):
+        self.assertEqual(len(must_include.removeprefix("- Must include: ").split(",")), 5)
+        for anchor in (
+            "Nilo",
+            "Mara",
+            "moonbell",
+            "wind-carved island village",
+            "red wool scarf",
+        ):
             self.assertIn(anchor, must_include)
             self.assertGreaterEqual(canvas.casefold().count(anchor.casefold()), 2)
         self.assertNotIn("tragic ending", must_include)
+        self.assertIn(
+            "1. At a wind-carved island village during the first snow, Nilo and Mara "
+            "examine a red wool scarf after a young fox named Nilo must return a stolen "
+            "moonbell",
+            canvas,
+        )
+
+    def test_hidden_plan_chooses_a_concrete_object_not_a_name_or_generic_verb(self) -> None:
+        canvas, _, _ = app.prepare_studio_story(
+            "A small favor sends Ada Choi-Wells after a copper compass that points "
+            "toward promises people have forgotten.",
+            "Folklore",
+            4,
+            "Ada Choi-Wells, a watchmaker who keeps other people's promises",
+            "A rain-bright canal market",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+        must_include = next(
+            line for line in canvas.splitlines() if line.startswith("- Must include:")
+        )
+        self.assertIn("copper compass", must_include)
+        self.assertNotIn("begins", must_include.casefold())
+        self.assertNotIn("choi-wells and", must_include.casefold())
+
+    def test_default_six_scene_plan_has_distinct_causal_beats(self) -> None:
+        canvas, _, _ = app.prepare_studio_story(
+            "A fox must return a moonbell before the winter tide.",
+            "Cozy fantasy",
+            6,
+            "Nilo, a cautious young fox\nMara, an elderly lighthouse keeper",
+            "A wind-carved island village",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+        beats = app._markdown_section(canvas, "Beats")
+        lines = re.findall(r"^\d+\. (.+)$", beats, re.MULTILINE)
+        self.assertEqual(len(lines), 6)
+        self.assertEqual(len(set(lines)), 6)
+        self.assertNotIn("Following begins", beats)
+        self.assertIn("- Aim for 55 to 100 words in each scene.", canvas)
+        self.assertIn(
+            "- Keep later and final scenes as fully developed as the first; do not "
+            "compress them below the word target.",
+            canvas,
+        )
+        self.assertIn(
+            "- In the final scene, explicitly perform the central actions named "
+            "in the story idea, with their objects, and show the result on-page; "
+            "do not end with them merely planned, attempted, promised, or still "
+            "waiting to happen.",
+            canvas,
+        )
+        self.assertIn(
+            "completes the actions required by the story idea on-page",
+            lines[-1],
+        )
+
+    def test_historical_v1_prompt_omits_v2_completion_guidance(self) -> None:
+        canvas, _, _ = app.prepare_story(
+            "A fox must return a moonbell before the winter tide.",
+            "Cozy fantasy",
+            2,
+            "Nilo, a cautious young fox",
+            "A wind-carved island village",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+        self.assertNotIn("completed on-page", canvas)
+        self.assertNotIn("merely planning or attempting it", canvas)
+        self.assertNotIn("later and final scenes", canvas)
+        self.assertNotIn("with their objects", canvas)
+
+    def test_single_character_default_beats_use_singular_verbs(self) -> None:
+        canvas, _, _ = app.prepare_studio_story(
+            "A ferryperson finds a moonbell beneath the last crossing.",
+            "Folklore",
+            6,
+            "Orra, a practical ferryperson",
+            "A braided river at first frost",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+        beats = app._markdown_section(canvas, "Beats")
+        self.assertIn("Orra examines", beats)
+        self.assertIn("Orra tests", beats)
+        self.assertIn("Orra combines", beats)
+
+    def test_one_scene_v2_plan_requires_completed_actions_and_results(self) -> None:
+        canvas, _, _ = app.prepare_studio_story(
+            "A ferryperson must repair the moonbell and reopen the crossing.",
+            "Folklore",
+            1,
+            "Orra, a practical ferryperson",
+            "A braided river at first frost",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+        beats = app._markdown_section(canvas, "Beats")
+        self.assertIn("Orra examines", beats)
+        self.assertIn("completes every central action", beats)
+        self.assertIn("with its object", beats)
+        self.assertIn("shows the result", beats)
 
     def test_blank_optional_gradio_values_accept_none(self) -> None:
         canvas, story_input, tokens = app.prepare_story(
@@ -351,6 +608,50 @@ class StudioPresentationTests(unittest.TestCase):
                 with self.assertRaises(app.StudioError):
                     app._scene_count(value)
 
+    def test_scene_stepper_clamps_and_disables_its_endpoints(self) -> None:
+        count, minus, plus = app.decrease_scene_count(2)
+        self.assertEqual(count, 1)
+        self.assertFalse(minus["interactive"])
+        self.assertTrue(plus["interactive"])
+
+        count, minus, plus = app.increase_scene_count(5)
+        self.assertEqual(count, 6)
+        self.assertTrue(minus["interactive"])
+        self.assertFalse(plus["interactive"])
+
+        self.assertEqual(app.increase_scene_count(6)[0], 6)
+        self.assertEqual(app.decrease_scene_count(1)[0], 1)
+        self.assertEqual(
+            app.sync_scene_stepper(3),
+            (
+                {"interactive": True, "__type__": "update"},
+                {"interactive": True, "__type__": "update"},
+            ),
+        )
+        high, minus, plus = app.normalize_scene_stepper(9)
+        self.assertEqual(high, 6)
+        self.assertTrue(minus["interactive"])
+        self.assertFalse(plus["interactive"])
+        low, minus, plus = app.normalize_scene_stepper(-4)
+        self.assertEqual(low, 1)
+        self.assertFalse(minus["interactive"])
+        self.assertTrue(plus["interactive"])
+        self.assertEqual(app.normalize_scene_stepper(2.6)[0], 3)
+        self.assertEqual(
+            app.normalize_scene_stepper(None)[0], app.DEFAULT_SCENE_COUNT
+        )
+
+    def test_advanced_toggle_reports_explicit_on_and_off_states(self) -> None:
+        hidden, off = app.toggle_advanced_options(False)
+        shown, on = app.toggle_advanced_options(True)
+        self.assertFalse(hidden["visible"])
+        self.assertTrue(shown["visible"])
+        self.assertIn(">Off<", off)
+        self.assertIn("advanced-off", off)
+        self.assertIn(">On<", on)
+        self.assertIn("advanced-on", on)
+        self.assertIn('aria-live="polite"', on)
+
     def test_character_rows_stay_separate_in_the_hidden_canvas(self) -> None:
         combined = app._character_rows(
             "Mara, a careful mapmaker",
@@ -496,7 +797,7 @@ class HostedBoundaryTests(unittest.TestCase):
         self.assertIn("About them", labels)
         self.assertIn("Name (optional)", labels)
         self.assertIn("About them (optional)", labels)
-        self.assertIn("Use advanced options", labels)
+        self.assertIn("Advanced options", labels)
         self.assertIn("How many scenes?", labels)
         self.assertNotIn("Main characters", labels)
         character_rows = [
@@ -505,12 +806,24 @@ class HostedBoundaryTests(unittest.TestCase):
             if "character-card" in item.get("props", {}).get("elem_classes", [])
         ]
         self.assertEqual(len(character_rows), 2)
+        for label in ("Name", "Name (optional)"):
+            self.assertIn(
+                "character-name-field",
+                self._component(config, label).get("props", {}).get("elem_classes", []),
+            )
+        for label in ("About them", "About them (optional)"):
+            self.assertIn(
+                "character-about-field",
+                self._component(config, label).get("props", {}).get("elem_classes", []),
+            )
         self.assertNotIn("Story length", labels)
         self.assertIn("Download story as Markdown", labels)
         self.assertNotIn("Image prompt", labels)
         self.assertNotIn("Generated illustration", labels)
         self.assertNotIn("Find illustration plans", buttons)
         self.assertNotIn("Generate illustration", buttons)
+        self.assertIn("Decrease scenes", buttons)
+        self.assertIn("Increase scenes", buttons)
         self.assertIn("Write my story", buttons)
         self.assertIn("This is a focused, text-only story Studio", copy)
         for technical_label in (
@@ -551,10 +864,36 @@ class HostedBoundaryTests(unittest.TestCase):
         self.assertEqual(genre.get("value"), "Cozy fantasy")
         self.assertEqual(scene_component.get("type"), "number")
         self.assertEqual(scene.get("value"), app.DEFAULT_SCENE_COUNT)
-        self.assertEqual(scene.get("minimum"), app.MIN_SCENE_COUNT)
-        self.assertEqual(scene.get("maximum"), app.MAX_SCENE_COUNT)
+        self.assertIsNone(scene.get("info"))
+        # Bounds stay out of gr.Number so Gradio does not reject 9 before the
+        # blur normalizer can visibly clamp it to 6. Backend _scene_count stays
+        # strict and the stepper callbacks enforce the same 1-6 contract.
+        self.assertIsNone(scene.get("minimum"))
+        self.assertIsNone(scene.get("maximum"))
         self.assertEqual(scene.get("step"), 1)
         self.assertEqual(scene.get("precision"), 0)
+        self.assertEqual(scene.get("elem_id"), "scene-count-value")
+        self.assertIn("scene-stepper-value", scene.get("elem_classes", []))
+        decrease = next(
+            item
+            for item in config.get("components", [])
+            if item.get("props", {}).get("value") == "Decrease scenes"
+        )
+        increase = next(
+            item
+            for item in config.get("components", [])
+            if item.get("props", {}).get("value") == "Increase scenes"
+        )
+        self.assertEqual(decrease.get("props", {}).get("min_width"), 48)
+        self.assertEqual(increase.get("props", {}).get("min_width"), 48)
+        self.assertIn(
+            "scene-stepper-minus",
+            decrease.get("props", {}).get("elem_classes", []),
+        )
+        self.assertIn(
+            "scene-stepper-plus",
+            increase.get("props", {}).get("elem_classes", []),
+        )
         self.assertEqual(structure_component.get("type"), "radio")
         self.assertEqual(
             structure.get("choices"), list(app.STRUCTURE_OPTIONS)
@@ -581,6 +920,13 @@ class HostedBoundaryTests(unittest.TestCase):
             for item in config.get("components", [])
         }
         self.assertIn(scene_component.get("id"), write_dependency.get("inputs", []))
+        normalize_dependency = next(
+            item
+            for item in config.get("dependencies", [])
+            if (scene_component.get("id"), "blur") in item.get("targets", [])
+        )
+        self.assertIn(scene_component.get("id"), normalize_dependency.get("inputs", []))
+        self.assertIn(scene_component.get("id"), normalize_dependency.get("outputs", []))
         self.assertTrue(
             any(
                 component_types.get(component_id) != "state"
@@ -593,6 +939,12 @@ class HostedBoundaryTests(unittest.TestCase):
                 for component_id in write_dependency.get("outputs", [])
             )
         )
+        output_labels = [
+            item.get("props", {}).get("value")
+            for item in config.get("components", [])
+            if "output-brand" in item.get("props", {}).get("elem_classes", [])
+        ]
+        self.assertEqual(output_labels, ["## SmolGPT-Fables Output:"])
 
     def test_local_ui_matches_the_text_only_product_surface(self) -> None:
         with patch.dict(os.environ, {}, clear=True):
@@ -613,6 +965,8 @@ class HostedBoundaryTests(unittest.TestCase):
         self.assertNotIn("provider_status", api_names)
         self.assertNotIn("generate_illustration", api_names)
         self.assertIn("This is a focused, text-only story Studio", copy)
+        self.assertIn("SmolGPT-Fables Output:", copy)
+        self.assertIn(">Off<", copy)
         self.assertFalse(
             any(
                 item.get("type") == "dropdown"
@@ -623,6 +977,173 @@ class HostedBoundaryTests(unittest.TestCase):
 
 
 class RuntimeContractTests(unittest.TestCase):
+    def test_model_loader_selects_nested_smollm3_v5_contract(self) -> None:
+        class LoadedTokenizer(CharacterTokenizer):
+            chat_template = "pinned-smollm3-template"
+
+        class LoadedModel:
+            config = SimpleNamespace(max_position_embeddings=8192)
+
+            def __init__(self) -> None:
+                self.device = None
+                self.evaluating = False
+
+            def to(self, device):
+                self.device = device
+                return self
+
+            def eval(self):
+                self.evaluating = True
+                return self
+
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            (root / "model.safetensors").write_bytes(b"weights")
+            (root / "tokenizer.json").write_text("{}", encoding="utf-8")
+            (root / "config.json").write_text(
+                json.dumps(
+                    {
+                        "architectures": ["SmolLM3ForCausalLM"],
+                        "model_type": "smollm3",
+                        "max_position_embeddings": 8192,
+                    }
+                ),
+                encoding="utf-8",
+            )
+            (root / "training_manifest.json").write_text(
+                json.dumps(
+                    {
+                        "prompt_contract": {
+                            "format": app.SMOLLM3_CHAT_PROMPT_FORMAT,
+                            "sha256": contract.smollm3_prompt_contract_sha256(),
+                            "thinking": False,
+                        }
+                    }
+                ),
+                encoding="utf-8",
+            )
+            tokenizer = LoadedTokenizer()
+            model = LoadedModel()
+            with (
+                patch.object(app, "_MODEL_BUNDLE", None),
+                patch.object(app, "_resolve_model_root", return_value=root),
+                patch.object(app, "_select_device", return_value=app.torch.device("cpu")),
+                patch.object(
+                    app.AutoTokenizer,
+                    "from_pretrained",
+                    return_value=tokenizer,
+                ) as tokenizer_loader,
+                patch.object(
+                    app.AutoModelForCausalLM,
+                    "from_pretrained",
+                    return_value=model,
+                ) as model_loader,
+            ):
+                bundle = app.load_model_bundle(force=True)
+
+        self.assertEqual(bundle.prompt_format, app.SMOLLM3_CHAT_PROMPT_FORMAT)
+        self.assertIs(bundle.tokenizer, tokenizer)
+        self.assertIs(bundle.model, model)
+        self.assertEqual(model.device, app.torch.device("cpu"))
+        self.assertTrue(model.evaluating)
+        self.assertFalse(tokenizer_loader.call_args.kwargs["trust_remote_code"])
+        self.assertFalse(model_loader.call_args.kwargs["trust_remote_code"])
+
+    def test_standard_chat_runtime_enforces_the_evaluated_2048_context(self) -> None:
+        class OversizedChatTokenizer(CharacterTokenizer):
+            chat_template = "fake"
+
+            def apply_chat_template(self, *args, **kwargs):
+                del args, kwargs
+                return [self.bos_token_id, *([7] * 2048)]
+
+        bundle = SimpleNamespace(
+            tokenizer=OversizedChatTokenizer(),
+            model=SimpleNamespace(
+                config=SimpleNamespace(max_position_embeddings=8192)
+            ),
+            device=app.torch.device("cpu"),
+            prompt_format=app.CHAT_PROMPT_FORMAT,
+        )
+        with self.assertRaisesRegex(app.StudioError, "supports 2048"):
+            app.generate_continuation(
+                bundle,
+                (
+                    "# Story: Test\n\n- Scene Count: 1\n\n"
+                    "- Target scenes: 1\n\n## Story\n\n"
+                ),
+                temperature=0.0,
+                top_p=1.0,
+                top_k=0,
+                repetition_penalty=1.0,
+                max_new_tokens=1,
+            )
+
+    def test_smollm3_v5_runtime_uses_exact_4096_context_and_disables_thinking(self) -> None:
+        class SizedSmolLM3Tokenizer(CharacterTokenizer):
+            chat_template = "fake-smollm3-template"
+
+            def __init__(self, token_count: int) -> None:
+                self.token_count = token_count
+                self.enable_thinking_values = []
+
+            def apply_chat_template(
+                self,
+                messages,
+                *,
+                add_generation_prompt,
+                tokenize,
+                enable_thinking,
+            ):
+                del messages, add_generation_prompt
+                self.enable_thinking_values.append(enable_thinking)
+                self.assert_tokenize = tokenize
+                return [self.bos_token_id, *([7] * (self.token_count - 1))]
+
+        model = SimpleNamespace(config=SimpleNamespace(max_position_embeddings=8192))
+        accepted_tokenizer = SizedSmolLM3Tokenizer(2049)
+        accepted = SimpleNamespace(
+            tokenizer=accepted_tokenizer,
+            model=model,
+            device=app.torch.device("cpu"),
+            prompt_format=app.SMOLLM3_CHAT_PROMPT_FORMAT,
+        )
+        result = app.generate_continuation_with_trace(
+            accepted,
+            (
+                "# Story: Test\n\n- Scene Count: 1\n\n"
+                "- Target scenes: 1\n\n## Story\n\n"
+            ),
+            temperature=0.0,
+            top_p=1.0,
+            top_k=0,
+            repetition_penalty=1.0,
+            max_new_tokens=0,
+        )
+        self.assertEqual(result.trace.requested_token_budget, 0)
+        self.assertEqual(accepted_tokenizer.enable_thinking_values, [False])
+        self.assertTrue(accepted_tokenizer.assert_tokenize)
+
+        oversized = SimpleNamespace(
+            tokenizer=SizedSmolLM3Tokenizer(4096),
+            model=model,
+            device=app.torch.device("cpu"),
+            prompt_format=app.SMOLLM3_CHAT_PROMPT_FORMAT,
+        )
+        with self.assertRaisesRegex(app.StudioError, "supports 4096"):
+            app.generate_continuation_with_trace(
+                oversized,
+                (
+                    "# Story: Test\n\n- Scene Count: 1\n\n"
+                    "- Target scenes: 1\n\n## Story\n\n"
+                ),
+                temperature=0.0,
+                top_p=1.0,
+                top_k=0,
+                repetition_penalty=1.0,
+                max_new_tokens=1,
+            )
+
     def test_doodle_system_is_bundled_accessible_and_versioned(self) -> None:
         source = (SPACE_DIR / "app.py").read_text(encoding="utf-8")
         self.assertIn('RELEASE_VERSION = "v1"', source)
@@ -635,6 +1156,46 @@ class RuntimeContractTests(unittest.TestCase):
         self.assertIn('aria-live="{live}"', source)
         self.assertIn('outline: 3px solid var(--color-focus)', source)
         self.assertIn('interactive=False', source)
+        self.assertIn('button.scene-stepper-minus::before', source)
+        self.assertIn('button.scene-stepper-plus::before', source)
+        self.assertIn('min-height: 48px !important', source)
+        self.assertIn('touch-action: manipulation', source)
+        self.assertIn('button:disabled', source)
+        self.assertIn('input[type="radio"]:checked', source)
+        self.assertIn(
+            'radial-gradient(circle at center, var(--color-primary)', source
+        )
+        self.assertIn('input[type="checkbox"]:checked', source)
+        self.assertIn('--color-success-ink: #0f6b31', source)
+        self.assertIn('--color-secondary: #b9eaff', source)
+        self.assertNotIn('[role="radiogroup"]', source)
+        self.assertIn(
+            '.advanced-panel fieldset:has(input[type="radio"]) > .wrap', source
+        )
+        self.assertIn(
+            '.advanced-panel label:has(input[type="radio"])', source
+        )
+        self.assertIn('.advanced-panel input[type="radio"]', source)
+        self.assertIn(
+            '.advanced-panel label:has(input[type="radio"]) > span', source
+        )
+        self.assertIn('flex: 0 0 20px !important', source)
+        self.assertIn('.advanced-panel:has(.advanced-panel)', source)
+        self.assertIn(
+            '.advanced-panel .advanced-panel > .styler', source
+        )
+        self.assertIn(
+            '.scene-stepper-field:has(.scene-stepper-field)', source
+        )
+        self.assertIn(
+            '.scene-stepper-field .scene-stepper-field > .styler', source
+        )
+        self.assertIn('max-width: calc(100vw - 24px)', source)
+        self.assertIn('.character-list .character-list > .styler', source)
+        self.assertIn('.character-name-field textarea', source)
+        self.assertIn('.character-about-field textarea', source)
+        self.assertIn('@media (max-width: 520px)', source)
+        self.assertIn('role="status" aria-live="polite"', source)
         for filename in (
             "DeliusSwashCaps-Regular.ttf",
             "JetBrainsMono-Regular.ttf",
@@ -645,11 +1206,19 @@ class RuntimeContractTests(unittest.TestCase):
 
     def test_checked_in_model_repo_fallback_is_visible_and_not_fake(self) -> None:
         self.assertEqual(app.DEFAULT_MODEL_REPO, "neonforestmist/smolgpt-fables")
-        with patch.dict(os.environ, {}, clear=True):
-            with self.assertRaisesRegex(app.ArtifactError, "configured"):
+        self.assertEqual(
+            app.DEFAULT_MODEL_REVISION,
+            "4245b8a4359e4490be58aaf8ac919dc371b6570e",
+        )
+        with (
+            patch.dict(os.environ, {}, clear=True),
+            patch.object(app, "_MODEL_BUNDLE", None),
+        ):
+            with self.assertRaisesRegex(app.ArtifactError, "download on first generation"):
                 app._resolve_model_root(download=False)
             status = app.model_status_html()
         self.assertIn("Getting SmolGPT ready", status)
+        self.assertIn("pinned story model", status)
         self.assertNotIn("demo story", status.lower())
         source = (SPACE_DIR / "app.py").read_text(encoding="utf-8")
         readme = (SPACE_DIR / "README.md").read_text(encoding="utf-8")
@@ -659,7 +1228,13 @@ class RuntimeContractTests(unittest.TestCase):
     def test_transformers_artifact_contract(self) -> None:
         with tempfile.TemporaryDirectory() as temporary:
             root = Path(temporary)
-            for name in app.MODEL_ARTIFACT_FILES:
+            for name in (
+                "model.safetensors",
+                "config.json",
+                "configuration_smolgpt.py",
+                "modeling_smolgpt.py",
+                "tokenizer.json",
+            ):
                 (root / name).write_text("", encoding="utf-8")
             (root / "config.json").write_text(
                 json.dumps(
@@ -676,11 +1251,29 @@ class RuntimeContractTests(unittest.TestCase):
             config = app._validate_model_root(root)
         self.assertEqual(config["model_type"], "smolgpt")
 
+    def test_standard_transformers_artifact_contract(self) -> None:
+        with tempfile.TemporaryDirectory() as temporary:
+            root = Path(temporary)
+            (root / "model.safetensors").write_bytes(b"weights")
+            (root / "tokenizer.json").write_text("{}", encoding="utf-8")
+            (root / "config.json").write_text(
+                json.dumps(
+                    {
+                        "architectures": ["LlamaForCausalLM"],
+                        "model_type": "llama",
+                        "max_position_embeddings": 8192,
+                    }
+                ),
+                encoding="utf-8",
+            )
+            config = app._validate_model_root(root)
+        self.assertEqual(config["model_type"], "llama")
+
     def test_space_has_no_legacy_pt_loader(self) -> None:
         source = (SPACE_DIR / "app.py").read_text(encoding="utf-8")
         self.assertIn("AutoTokenizer.from_pretrained", source)
         self.assertIn("AutoModelForCausalLM.from_pretrained", source)
-        self.assertIn("trust_remote_code=True", source)
+        self.assertIn('trust_remote_code=artifact_kind == "custom"', source)
         self.assertNotIn("torch.load", source)
         self.assertNotIn("model.pt", source)
 
@@ -698,7 +1291,35 @@ class RuntimeContractTests(unittest.TestCase):
         self.assertIn("sdk: gradio", readme)
         self.assertIn("sdk_version: 6.19.0", readme)
         self.assertIn("app_file: app.py", readme)
-        self.assertIn("python_version: \"3.11\"", readme)
+        self.assertIn("python_version: \"3.12.12\"", readme)
+        self.assertIn("standard `LlamaForCausalLM` artifact", readme)
+        self.assertIn("`HuggingFaceTB/SmolLM2-1.7B-Instruct`", readme)
+        self.assertIn("audited\nnatural-v6 curriculum", readme)
+        self.assertIn("exact natural-v6\nprompt-contract digest", readme)
+        self.assertIn("**SmolGPT-Fables Output:**", readme)
+        self.assertIn("`neonforestmist/smolgpt-fables`", readme)
+        self.assertIn("4245b8a4359e4490be58aaf8ac919dc371b6570e", readme)
+        self.assertIn("@spaces.GPU(duration=120)", readme)
+        self.assertIn(
+            "https://huggingface.co/datasets/neonforestmist/smolgpt-markdown-stories",
+            readme,
+        )
+        self.assertNotIn("SmolLM3 v5", readme)
+        self.assertNotIn("smolgpt-fables-smollm3-chat-v5", readme)
+        lowered = readme.casefold()
+        for phrase in (
+            "draw things",
+            "image generation",
+            "illustration orchestration",
+            "openai",
+            "iphone",
+            "mobile",
+            "phone",
+            "research preview",
+            "candidate",
+            "experimental",
+        ):
+            self.assertNotIn(phrase, lowered)
 
     def test_ui_source_avoids_forbidden_dash_characters(self) -> None:
         source = (SPACE_DIR / "app.py").read_text(encoding="utf-8")