fix: address PR review on loopback host, versioning, and docs

Author: clean6378-max-it

CHANGELOG.md

@@ -4,12 +4,12 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.1.0] - 2026-06-02
+## [Unreleased]
 
 ### Added
 
-- `__version__` in `app.py` for release tracking
-- Startup guard refusing `--debug` with a non-loopback `--host`
+- `__version__` in `app.py` for release tracking (`0.1.0.dev0` until the first `v0.1.0` git tag)
+- Startup guard refusing `--debug` with a non-loopback `--host` (including bracketed IPv6 loopback such as `[::1]`)
 - [Deprecation policy](docs/deprecation-policy.md) for API and JSON field changes
 - API field **stability** tables in `docs/api-reference.md` (stable / experimental / deprecated)
 
@@ -20,5 +20,3 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Deprecated
 
 - `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

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 when starting via `python app.py`, not `flask run` or WSGI)
+- `--debug` — Flask/Werkzeug debug mode (loopback hosts only; enforced when starting via `python app.py`, not `flask run` or WSGI). Extending the guard to `FLASK_DEBUG` / `flask run` is a planned follow-up.
 
 ## API and release policy
 

app.py

@@ -1,6 +1,6 @@
 """Flask app that serves the web GUI for browsing sessions."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.0.dev0"
 
 import argparse
 import os
@@ -15,13 +15,21 @@
 from utils.exclusion_rules import resolve_exclusion_rules_path, load_rules
 
 
+def _normalize_bind_host(host: str) -> str:
+    """Lowercase host for checks; strip optional IPv6 brackets (e.g. ``[::1]`` → ``::1``)."""
+    h = (host or "").strip().lower()
+    if len(h) >= 2 and h.startswith("[") and h.endswith("]"):
+        return h[1:-1]
+    return h
+
+
 def is_loopback_host(host: str) -> bool:
     """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.
+    Accepts ``127.0.0.1``, ``localhost``, ``::1``, ``[::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()
+    h = _normalize_bind_host(host)
     if h in ("127.0.0.1", "localhost", "::1"):
         return True
     if h.startswith("127.") and h.count(".") == 3:
@@ -52,7 +60,7 @@ def validate_startup_cli(args: argparse.Namespace) -> None:
     if args.debug and not is_loopback_host(args.host):
         print(
             "error: --debug is only allowed with a loopback --host "
-            "(127.0.0.1, localhost, ::1, or 127.x.x.x). "
+            "(127.0.0.1, localhost, ::1, [::1], or 127.x.x.x). "
             "Combining --debug with a network-visible --host exposes the "
             "Werkzeug debugger and session data to other machines.",
             file=sys.stderr,

docs/api-reference.md

@@ -6,7 +6,7 @@ HTTP API for **claude-code-chat-browser**. All `/api/*` routes return JSON unles
 
 **Source of truth for error codes:** [`api/error_codes.py`](../api/error_codes.py)
 
-**Field stability:** [`deprecation-policy.md`](deprecation-policy.md)
+**Deprecation and removal:** See [`deprecation-policy.md`](deprecation-policy.md) for how stability labels are applied and fields are removed. Field labels are defined in [API field stability](#api-field-stability) below.
 
 ---
 

docs/deprecation-policy.md

@@ -25,7 +25,7 @@ A deprecated field may be removed when:
 - The bundled SPA no longer reads the field, and
 - Tests and CHANGELOG document the removal.
 
-For fields actively read by the bundled SPA (which does not track an external API version), the deprecation period will span **at least two releases** so the SPA and policy can be updated in the same release cycle as the final removal.
+For fields actively read by the bundled SPA (which does not track an external API version), removal happens no earlier than **two tagged releases** after the release that documented the deprecation in CHANGELOG (for example, deprecated in `0.1.0`, removable from `0.3.0` at earliest when versions advance `0.1.0` → `0.2.0` → `0.3.0`), and no earlier than **14 calendar days** after that deprecation announcement.
 
 ## Example (in progress)
 
@@ -35,4 +35,12 @@ For fields actively read by the bundled SPA (which does not track an external AP
 
 ## Versioning
 
-Release versions follow `MAJOR.MINOR.PATCH` in `app.__version__` and [CHANGELOG](../CHANGELOG.md). This project is pre-1.0; minor releases may add features; patch releases are fixes and documentation.
+Release versions follow `MAJOR.MINOR.PATCH` in `app.__version__` and [CHANGELOG](../CHANGELOG.md). Until the first git tag ships, `main` may carry a `.dev0` suffix (for example `0.1.0.dev0`); the CHANGELOG `[Unreleased]` section is the source of truth for what is not yet tagged.
+
+| Bump | Pre-1.0 meaning |
+|------|-----------------|
+| **Patch** | Bug fixes and documentation; no intentional API removals |
+| **Minor** | Additive API/features; deprecations may be announced |
+| **Major** | Reserved for the `1.0.0` line and later: signals a stable HTTP JSON contract for external integrators and may include breaking removals that completed their deprecation period |
+
+While the project is pre-1.0, treat **minor** bumps as the usual vehicle for deprecations and **patch** bumps for safe fixes.

tests/test_cli_args.py

@@ -321,7 +321,9 @@ def test_debug_explicit_true(self):
         args = parser.parse_args(["--debug"])
         assert args.debug is True
 
-    @pytest.mark.parametrize("host", ["127.0.0.1", "localhost", "::1", "127.0.0.2"])
+    @pytest.mark.parametrize(
+        "host", ["127.0.0.1", "localhost", "::1", "[::1]", "127.0.0.2"]
+    )
     def test_is_loopback_host_accepts_loopback(self, host: str) -> None:
         assert is_loopback_host(host)
 
@@ -340,7 +342,7 @@ 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)
 
-    @pytest.mark.parametrize("host", ["127.0.0.1", "localhost"])
+    @pytest.mark.parametrize("host", ["127.0.0.1", "localhost", "[::1]"])
     def test_validate_startup_cli_allows_loopback_debug(self, host: str) -> None:
         parser = build_cli_parser()
         args = parser.parse_args(["--host", host, "--debug"])