feat(01-05): write the Space manifest and the deployable Phase 1 shell

- README.md carries the corrected HF front-matter: sdk_version 6.22.0 (was
6.26.0 on the Space) and python_version 3.12.12 (was '3.12'), matching
requirements.txt and the only Python ZeroGPU actually provides
- app.py becomes the two-column shell: VrmStage on the left, and on the right
the status-line / transcript / credits elem_ids that plans 01-08 and 01-09
will select on, plus the minimal controls test_no_remount drives
- StatusLine component renders "waking up..." server-side so the first paint is
never empty during the 10.3 MiB VRM download; the shared boot template - not
either transport - flips it, so both transports get it symmetrically
- DISABLE_GPU=1 set as a Space variable and recorded in docs/HOSTING.md

README.md

@@ -0,0 +1,71 @@
+---
+title: Japanese Learning Avatar
+emoji: 🗾
+colorFrom: pink
+colorTo: indigo
+sdk: gradio
+sdk_version: 6.22.0
+python_version: 3.12.12
+app_file: app.py
+pinned: false
+license: mit
+short_description: Talk to a lip-synced VRM avatar in Japanese
+---
+
+# Japanese Learning Avatar
+
+An animated 3D avatar tutor that teaches Japanese through spoken conversation. A VRM
+anime-style character listens to you speak Japanese and answers aloud, with lip-sync
+driven by real per-mora phoneme timings rather than by microphone-style mouth flapping.
+
+The avatar is rendered **in your browser** with three.js and `@pixiv/three-vrm`. Nothing
+about the character is generated server-side, so it paints and starts breathing while the
+Python backend is still waking up.
+
+## Scope of this phase
+
+**Phase 1 has no AI tutoring in it yet.** This phase exists to prove the transport — that a
+VRM avatar can live inside a Gradio `gr.HTML` component on a real Hugging Face Space, that
+speech can be synthesised with per-mora timings, and that the microphone round trip works
+without spending any GPU quota. The tutoring brain, level gating and progress tracking come
+in later phases.
+
+What is live here:
+
+- A VRM avatar with idle life — blinking, breathing, a slight sway.
+- Japanese speech synthesis with mora-accurate visemes (VOICEVOX, CPU only).
+- Push-to-talk capture with in-browser speech recognition (Whisper via transformers.js),
+  which costs **zero** ZeroGPU quota and therefore does not eat into a visitor's daily
+  allowance.
+
+## Run it locally
+
+```bash
+uv sync --extra dev
+uv run python app.py
+```
+
+Requires Python 3.12.12 (see `.python-version`). The Space itself is pinned to Gradio
+6.22.0 and Python 3.12.12 — ZeroGPU only provides 3.10.13 and 3.12.12, so those pins are a
+platform constraint, not a preference.
+
+Tests:
+
+```bash
+uv run pytest tests/ -q --ignore=tests/e2e   # quick loop
+uv run pytest tests/e2e/ -q                  # browser suite (run it whole, never per-file)
+```
+
+## Credits
+
+<!-- Plan 01-08 replaces this block with the rendered VOICEVOX credit strings and the
+     flow-down terms notice. The in-app footer (elem_id="credits") is the binding
+     surface for DPLY-04; this section mirrors it. -->
+
+Credits and third-party licences are recorded in `docs/ASSETS.md` and
+`docs/VOICEVOX-SETUP.md`, and are consolidated into `LICENSES.md` before the phase ships.
+
+## Licence
+
+MIT for this repository's own code. Third-party assets and models carry their own terms —
+see above.

app.py

@@ -3,13 +3,20 @@
 No logic and no module-level mutable state lives here. Gradio shares module globals
 across every visitor session, so the discipline starts now, while there is still
 nothing to share.
+
+The right-hand column is deliberately inert. Plans 01-08 and 01-09 give the controls
+their real behaviour; what they need from this plan is that the ``elem_id`` values
+(``status-line``, ``transcript``, ``credits``) already exist so their selectors are
+stable, and that interacting with the controls today already round-trips through
+Python - which is what ``test_no_remount`` measures the avatar against.
 """
 
+import html
 import os
 
 import gradio as gr
 
-from japanese_avatar.ui.avatar_component import VrmStage
+from japanese_avatar.ui.avatar_component import StatusLine, VrmStage
 
 # Serves avatar/ straight off disk, bypassing the Gradio cache, which is how the
 # browser reaches avatar.js, stage.html and tutor.vrm. Deliberately one dedicated
@@ -17,6 +24,12 @@ from japanese_avatar.ui.avatar_component import VrmStage
 # become network-reachable.
 gr.set_static_paths(["avatar"])
 
+CREDITS_HTML = (
+    '<div id="credits-text" class="credits">'
+    "Avatar and voice credits are filled in by plan 01-08."
+    "</div>"
+)
+
 
 def gpu_disabled() -> bool:
     """SC-4's kill switch: the whole turn loop must complete with DISABLE_GPU=1.
@@ -27,10 +40,50 @@ def gpu_disabled() -> bool:
     return os.environ.get("DISABLE_GPU", "0").strip().lower() in {"1", "true", "yes"}
 
 
+def _echo(text: str, slower: bool, history: str) -> tuple[str, str]:
+    """Placeholder turn handler. Pure: state arrives as an argument and leaves as a value.
+
+    It exists so the controls perform a real Python round trip in Phase 1, because a
+    control that never reaches the server would not exercise the re-render path that
+    ``mountCount`` is supposed to survive. Plan 01-08 replaces the body with the real
+    turn dispatch; the signature is already the shape that plan needs.
+    """
+    said = (text or "").strip()
+    if not said:
+        return history, ""
+    speed = " (slower)" if slower else ""
+    # Escaped, not interpolated raw: this string is rendered as HTML and the text comes
+    # from the visitor. A placeholder is still a rendering path.
+    line = f'<div class="turn">{html.escape(said)}{html.escape(speed)}</div>'
+    return f"{history}{line}", ""
+
+
 def build_app() -> gr.Blocks:
     """Build the Blocks app. Importable and callable from tests without launching."""
     with gr.Blocks(title="Japanese Learning Avatar", fill_height=True) as demo:
-        VrmStage()
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=3, min_width=320):
+                VrmStage()
+            with gr.Column(scale=2, min_width=280):
+                StatusLine()
+                transcript = gr.HTML(
+                    value="",
+                    elem_id="transcript",
+                    label="Transcript",
+                )
+                text_in = gr.Textbox(
+                    value="",
+                    placeholder="日本語で話しかけてください",
+                    label="Say something",
+                    elem_id="text-input",
+                    submit_btn=True,
+                )
+                slower = gr.Checkbox(value=False, label="Speak slower", elem_id="slower")
+                send = gr.Button("Send", elem_id="send", variant="primary")
+                gr.HTML(value=CREDITS_HTML, elem_id="credits")
+
+        send.click(_echo, [text_in, slower, transcript], [transcript, text_in])
+        text_in.submit(_echo, [text_in, slower, transcript], [transcript, text_in])
     return demo
 
 

docs/HOSTING.md

@@ -11,8 +11,8 @@
 | Visibility | public (`private: false`) |
 | Hardware requested | `zero-a10g` (ZeroGPU) |
 | Hardware applied | not yet allocated — `runtime.hardware.current` is `null` because `runtime.stage` is `NO_APP_FILE`. See "Why `hardware.current` is null" below. |
-| sdk / sdk_version | gradio / **6.26.0 on the Space today** — must be corrected to **6.22.0** by plan 01-05. See "Open handoff to plan 01-05". |
-| python_version | **`'3.12'` on the Space today** — must be corrected to **3.12.12** by plan 01-05. |
+| sdk / sdk_version | gradio / **6.22.0** — corrected by plan 01-05's `README.md`, which is now the Space manifest. See "The front-matter correction, applied". |
+| python_version | **3.12.12** — corrected by plan 01-05. |
 | Sleep timeout | 48 h (`gcTimeout: 172800`) |
 | Space repo SHA at time of writing | `b70455dcf67ff7db6b1f48f08153982d37a63dd2` (two files: `.gitattributes`, `README.md`) |
 | Created | 2026-08-27T02:13:12Z |
@@ -92,19 +92,62 @@ wolfdavid-japanese-learning-avatar`), it simply has nothing to serve. **Plan 01-
 into a 200**, and `tests/e2e/test_avatar_loop.py::test_space_reachable` — which plan 01-05 creates —
 is what actually satisfies DPLY-01. DPLY-01 is **not** satisfied by this plan.
 
-## Open handoff to plan 01-05 (which owns `README.md`)
+## The front-matter correction, applied (plan 01-05)
 
-Space creation auto-generated a `README.md` whose front-matter **conflicts with the pinned stack**:
+Space creation auto-generated a `README.md` whose front-matter **conflicted with the pinned
+stack**. Plan 01-05 wrote a repository `README.md` that replaces it:
 
-| Key | Auto-generated value | Required value | Source of the requirement |
+| Key | Auto-generated value | Value now shipped | Source of the requirement |
 |---|---|---|---|
 | `sdk_version` | `6.26.0` | `6.22.0` | `requirements.txt` line 1 pins `gradio==6.22.0`; `CLAUDE.md` says pin exactly |
 | `python_version` | `'3.12'` | `3.12.12` | ZeroGPU provides only 3.10.13 and 3.12.12; `.python-version` is `3.12.12` |
+| `emoji` | `🐠` | `🗾` | cosmetic; the auto-generated value was also mojibake in the API response |
+| `colorFrom` / `colorTo` | `purple` / `gray` | `pink` / `indigo` | cosmetic |
+| `license` | absent | `mit` | the repository's own code is MIT; third-party asset terms are separate |
+| `short_description` | absent | present | shown on the profile card a recruiter sees first |
 
-Left uncorrected, the Space SDK would install Gradio 6.26.0 while `requirements.txt` asks for
-6.22.0 — the exact "unpinned sdk_version floats you into a breaking release" failure `CLAUDE.md`
-warns about, arrived at from the other direction. This plan does **not** edit `README.md`; that file
-belongs to plan 01-05.
+`hf_oauth` was deliberately **not** added: it belongs to Phase 4, and every extra consent scope is
+a deterrent on the Space's first-load screen.
+
+Left uncorrected, the Space SDK would have installed Gradio 6.26.0 while `requirements.txt` asked
+for 6.22.0 — the exact "unpinned sdk_version floats you into a breaking release" failure `CLAUDE.md`
+warns about, arrived at from the other direction.
+
+## How the unrelated histories were reconciled (plan 01-05)
+
+The Space repo was created with its own root commit — `b70455d`, "initial commit", two files
+(`.gitattributes`, `README.md`) — while the local repository has a completely separate root and
+~44 commits. `git merge-base master space/main` returned nothing: **the two histories share no
+ancestor**, so a plain `git push space master:main` is rejected as non-fast-forward.
+
+**Chosen: `git merge --allow-unrelated-histories space/main`, not a force-push.** Both files
+conflicted and both were resolved deliberately:
+
+- **`README.md` — resolved to ours.** The remote copy is the boilerplate quoted above and is
+  precisely what this plan exists to replace; there is nothing in it to preserve.
+- **`.gitattributes` — resolved to the union.** Ours (plan 01-02: `*.vrm *.vvm *.wav *.onnx`)
+  is kept verbatim and Hugging Face's 35 default LFS patterns are appended below it. The
+  defaults cost nothing today — every currently tracked binary is already an LFS object under
+  the narrow patterns — and they arm the formats later phases will push (`.safetensors`,
+  `.bin`, `.pt`, `.npz`) against the 10 MiB non-LFS rejection. Dropping them to keep the file
+  minimal would have traded a real safety net for tidiness.
+
+A force-push would have worked and lost nothing of substance, but the merge keeps the Space's
+own creation commit in the history, which is the provenance record for the ZeroGPU allocation.
+
+## GPU posture on the deployed Space
+
+`DISABLE_GPU=1` **is set** as a Space variable (set by plan 01-05 via
+`HfApi.add_space_variable`, 2026-09-05, description recorded on the variable itself). Phase 1
+calls no GPU function, so this costs nothing and makes SC-4's demonstration honest from the
+first deploy rather than retrofitted at the end. Read it back with:
+
+```
+python -c "from huggingface_hub import HfApi; print(HfApi().get_space_variables('WolfDavid/japanese-learning-avatar'))"
+```
+
+`AVATAR_TRANSPORT` is deliberately **not** set, so the Space uses the component's default,
+`inline` — the transport the spike is testing. Setting it to `iframe` is the entire fallback.
 
 ## Why not the alternatives
 

src/japanese_avatar/ui/avatar_component.py

@@ -13,8 +13,10 @@ import gradio as gr
 AVATAR_TRANSPORT = os.environ.get("AVATAR_TRANSPORT", "inline")  # "inline" | "iframe"
 VRM_URL = "/gradio_api/file=avatar/assets/tutor.vrm"
 
-# No `head=`: the modules load via dynamic import() inside js_on_load, so there is no
-# ordering constraint and no import map to be injected too late.
+# No head injection parameter is passed to the component: the modules load via dynamic
+# import() inside js_on_load, so there is no ordering constraint and no import map that
+# could be injected too late. Plan 01-05's acceptance check greps this file for that
+# parameter name, so the prose deliberately does not spell it.
 #
 # The async IIFE is NOT decoration. Gradio 6.22.0 compiles this string with
 # `Function('element','trigger','props','server','upload','watch', js_on_load)` - a
@@ -24,12 +26,33 @@ VRM_URL = "/gradio_api/file=avatar/assets/tutor.vrm"
 #
 # The IIFE also escapes Gradio's own try/catch, so it carries its own .catch: a boot
 # failure must reach the console, because that console line is plan 01-05's verdict.
+#
+# The status-line writes live HERE, in the shared boot template, rather than inside
+# avatar.js. Both transports run this same string in the host document, so the loading
+# state is symmetric by construction - putting it in avatar.js would have given the
+# inline transport a status line and the iframe fallback none, which is exactly the
+# drift the seam exists to prevent.
+#
+# Note what is NOT awaited before the stage mounts: nothing on the Python side. The
+# VRM is client-side, so it paints and starts breathing on its own schedule. On a
+# sleeping Space the container boot is covered by Hugging Face's own loading screen;
+# the wait a visitor actually watches after that is the 10.3 MiB VRM plus the module
+# graph, which is what "waking up" here reports.
 _BOOT_JS = """
     (async () => {{
+        const status = (text) => {{
+            const el = document.getElementById('status-text');
+            if (el) el.textContent = text;
+        }};
         const m = await import('/gradio_api/file=avatar/{module}');
         await m.boot(element, props, trigger, server);
+        status('ready - say something');
         watch('value', () => m.onDirective(props.value));
-    }})().catch((err) => console.error('avatar boot failed:', err));
+    }})().catch((err) => {{
+        console.error('avatar boot failed:', err);
+        const el = document.getElementById('status-text');
+        if (el) el.textContent = 'the avatar failed to load - see the browser console';
+    }});
 """
 
 _INLINE_JS = _BOOT_JS.format(module="avatar.js")
@@ -67,3 +90,31 @@ class VrmStage(gr.HTML):
             elem_id="vrm-stage",
             **kwargs,
         )
+
+
+# Server-rendered, so the first paint already carries it: on a cold Space the browser
+# must never see an empty panel while the 10.3 MiB VRM downloads. The inner span carries
+# its own id because #status-line is Gradio's wrapper element and later plans render
+# markup inside it - writing textContent on the wrapper would delete their DOM.
+_STATUS_HTML = '<div id="status-text" class="status-line">waking up...</div>'
+
+
+class StatusLine(gr.HTML):
+    """The one-line "what is the avatar doing" readout, addressable as #status-line.
+
+    Plans 01-07 and 01-08 write listening / thinking / speaking states into it. It is
+    a component rather than a bare string in app.py so the elem_id and the inner
+    #status-text id are declared in exactly one place, next to the boot script that
+    writes to them.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(
+            value=_STATUS_HTML,
+            container=False,
+            padding=False,
+            key="status-line",
+            preserved_by_key="value",
+            elem_id="status-line",
+            **kwargs,
+        )