docs: address PR review on debug guard scope and deprecation wording

Author: clean6378-max-it

CHANGELOG.md

@@ -21,4 +21,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - `export_count` on `GET /api/export/state` (documented only; still returned). Use `last_export_session_count`. Removal planned in a follow-up release per [deprecation policy](docs/deprecation-policy.md).
 
-[0.1.0]: https://github.com/cppalliance/claude-code-chat-browser/releases/tag/v0.1.0
+[0.1.0]: https://github.com/cppalliance/claude-code-chat-browser/releases

CONTRIBUTING.md

@@ -41,7 +41,7 @@ Useful flags:
 - `--base-dir PATH` — point at a different `projects/` tree (for tests or fixtures)
 - `--exclude-rules PATH` — session exclusion rules file
 - `--host 0.0.0.0` — listen on all interfaces (use only on trusted networks; never with `--debug`)
-- `--debug` — Flask/Werkzeug debug mode (loopback hosts only; enforced at startup)
+- `--debug` — Flask/Werkzeug debug mode (loopback hosts only; enforced when starting via `python app.py`, not `flask run` or WSGI)
 
 ## API and release policy
 

README.md

@@ -67,6 +67,7 @@ python app.py --base-dir /path/to/claude/projects
 > which allows arbitrary code execution from any browser that can reach the server.
 > For typical local browsing, keep the default `--host 127.0.0.1` and omit `--debug`.
 > The server **refuses to start** if `--debug` is combined with a non-loopback `--host` (e.g. `0.0.0.0`).
+> That check runs only when you start the app with **`python app.py`** (not via `flask run` or other WSGI entrypoints).
 
 ### CLI Export
 

app.py

@@ -16,7 +16,11 @@
 
 
 def is_loopback_host(host: str) -> bool:
-    """True if ``host`` binds only to the local machine (safe with ``--debug``)."""
+    """True if ``host`` binds only to the local machine (safe with ``--debug``).
+
+    Accepts ``127.0.0.1``, ``localhost``, ``::1``, and other ``127.x.x.x`` addresses.
+    Rejects all-interfaces forms such as ``0.0.0.0`` and bare ``::`` (not loopback).
+    """
     h = (host or "").strip().lower()
     if h in ("127.0.0.1", "localhost", "::1"):
         return True

docs/deprecation-policy.md

@@ -6,7 +6,7 @@ This document defines how **claude-code-chat-browser** evolves its HTTP JSON API
 
 1. **Documented fields are a contract.** See [API reference](api-reference.md) — each field is marked `stable`, `experimental`, or `deprecated`.
 2. **Additive first.** Prefer adding a new field over renaming an existing one.
-3. **Deprecate before removing.** A deprecated field remains in responses for at least **one release** after the deprecation is announced in [CHANGELOG](../CHANGELOG.md) and the API reference.
+3. **Deprecate before removing.** A deprecated field remains in responses for at least **one release** after the deprecation is announced in [CHANGELOG](../CHANGELOG.md) and the API reference. Fields still read by the bundled SPA need **at least two releases** — see [Removal criteria](#removal-criteria) below.
 4. **SPA and scripts.** Update `static/js/*.js` and any internal callers before removing a field.
 
 ## How we announce deprecation

tests/test_cli_args.py

@@ -340,9 +340,10 @@ def test_is_loopback_host_accepts_loopback(self, host: str) -> None:
     def test_is_loopback_host_rejects_non_loopback(self, host: str) -> None:
         assert not is_loopback_host(host)
 
-    def test_validate_startup_cli_allows_loopback_debug(self) -> None:
+    @pytest.mark.parametrize("host", ["127.0.0.1", "localhost"])
+    def test_validate_startup_cli_allows_loopback_debug(self, host: str) -> None:
         parser = build_cli_parser()
-        args = parser.parse_args(["--host", "127.0.0.1", "--debug"])
+        args = parser.parse_args(["--host", host, "--debug"])
         validate_startup_cli(args)
 
     def test_validate_startup_cli_rejects_non_loopback_debug(