Merge pull request #27 from IgnazioDS/branch/release-v2.6.0

[codex] v2.6.0 DX and docs consolidation

Author: IgnazioDS

.env.example

@@ -38,13 +38,14 @@ CLOUD_BIND_HOST=127.0.0.1
 # Admin dashboard server auth
 # ---------------------------------------------------------------------------
 ADMIN_UI_USERNAME=admin
-# direct hash for non-Docker admin runs; keep bcrypt values single-quoted in .env
-# to avoid docker compose interpolation of "$" segments.
+# Dev-safe defaults below map to ADMIN_UI_PASSWORD=admin123! so a fresh clone can
+# follow the runbook without hand-editing auth secrets first. Keep direct bcrypt
+# hashes single-quoted in .env to avoid docker compose interpolation of "$" segments.
 # example: cd apps/admin && node -e "const b=require('bcryptjs'); console.log(b.hashSync('admin123!', 12));"
-ADMIN_UI_PASSWORD_HASH='REPLACE_WITH_BCRYPT_HASH'
+ADMIN_UI_PASSWORD_HASH='$2a$12$bBcV9Ds2tcdutyB7gyXLf.GGxhg0Fwgu.MnQ7EAdAqRqCPqjMRanu'
 # Docker Compose-safe variant (base64 of the bcrypt hash above)
 # example: cd apps/admin && node -e "const b=require('bcryptjs'); process.stdout.write(Buffer.from(b.hashSync('admin123!', 12), 'utf8').toString('base64'));"
-ADMIN_UI_PASSWORD_HASH_B64=REPLACE_WITH_BCRYPT_HASH_BASE64
+ADMIN_UI_PASSWORD_HASH_B64=JDJhJDEyJGJCY1Y5RHMydGNkdXR5QjdneVhMZi5HR3hoZzBGd2d1Lk1uUTdFQWRBcVJxQ1Bxak1SYW51
 ADMIN_UI_SESSION_SECRET=dev-admin-session-secret-change-me
 ADMIN_UI_SESSION_TTL_MINUTES=480
 ADMIN_UI_SESSION_SECURE=0

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to SentinelID are documented in this file.
 
+## v2.6.0 (2026-03-07)
+
+### DX and Docs Consolidation
+- Advanced the SentinelID release line to `v2.6.0` across release-critical docs, Make help text, desktop package/config metadata, pilot evidence targets, and cloud API metadata.
+- Added canonical Make wrappers for developer setup and doc validation (`make install-dev`, `make check-version-consistency`, `make check-docs-consistency`, `make check-fresh-clone`) so local and CI guidance can point to one command set.
+- Rewrote the runbook beginner path around `make install-dev`, `make demo-up`, `make demo-verify`, `make demo`, and `make demo-down`, and updated `.env.example` with dev-safe admin auth defaults so fresh clones no longer require manual env debugging.
+- Added `scripts/release/check_docs_consistency.sh` to fail `make release-check` when key docs drift back to raw script invocations, obsolete env var names, or legacy phase-doc clutter.
+- Created `docs/archive/` policy guidance and added coverage that root `docs/` stays free of `phase*.md` files.
+
 ## v2.5.0 (2026-03-07)
 
 ### Operational Robustness and Observability

Makefile

@@ -1,14 +1,18 @@
 .PHONY: help \
+	install-dev \
 	demo-up \
 	demo-desktop \
 	demo-desktop-verify \
 	demo \
 	demo-verify \
 	demo-down \
 	demo-checklist \
+	check-fresh-clone \
 	check-no-orphans \
 	check-no-duplicates \
 	check-invariants \
+	check-version-consistency \
+	check-docs-consistency \
 	check-release-tag \
 	gen-types \
 	bundle-edge \
@@ -43,7 +47,10 @@
 	clean
 
 help:
-	@echo "SentinelID v2.5.0 Commands"
+	@echo "SentinelID v2.6.0 Commands"
+	@echo ""
+	@echo "Setup"
+	@echo "  make install-dev         Install edge/admin/desktop dev dependencies from lockfiles"
 	@echo ""
 	@echo "Demo"
 	@echo "  make demo-up             Start cloud/admin/postgres and wait for health"
@@ -53,9 +60,12 @@ help:
 	@echo "  make demo-desktop-verify Launch desktop and auto-close (CI-friendly, no Docker)"
 	@echo "  make demo-down           Stop demo stack (use V=1 to remove volumes)"
 	@echo "  make demo-checklist      Print demo checklist path (OPEN=1 to open locally)"
+	@echo "  make check-fresh-clone   Clone current branch to a temp dir and run the beginner path"
 	@echo "  make check-no-orphans    Verify no orphan edge process is running"
 	@echo "  make check-no-duplicates Verify duplicate source artifact pairs are absent"
 	@echo "  make check-invariants    Validate loopback/auth/support-bundle runtime invariants"
+	@echo "  make check-version-consistency Verify release-critical version markers stay aligned"
+	@echo "  make check-docs-consistency Validate canonical docs commands and env names"
 	@echo "  make check-release-tag   Verify RELEASE_EXPECT_TAG points to HEAD"
 	@echo ""
 	@echo "Build"
@@ -96,6 +106,9 @@ help:
 	@echo "Docs"
 	@echo "  RUNBOOK.md is the authoritative run/test path"
 
+install-dev:
+	@./scripts/install_dev.sh
+
 bundle-edge:
 	@./scripts/bundle_edge_venv.sh
 
@@ -125,12 +138,21 @@ demo-checklist:
 		fi; \
 	fi
 
+check-fresh-clone:
+	@./scripts/check_fresh_clone_bootstrap.sh
+
 check-no-orphans:
 	@./scripts/check_no_orphan_edge.sh
 
 check-no-duplicates:
 	@./scripts/release/check_no_duplicate_pairs.sh
 
+check-version-consistency:
+	@./scripts/release/check_version_consistency.sh
+
+check-docs-consistency:
+	@./scripts/release/check_docs_consistency.sh
+
 check-release-tag:
 	@./scripts/release/check_release_tag_alignment.sh
 

RUNBOOK.md

@@ -1,4 +1,4 @@
-# SentinelID Runbook (v2.5.0)
+# SentinelID Runbook (v2.6.0)
 
 This is the single source of truth for local setup, run, and validation.
 
@@ -9,10 +9,9 @@ This is the single source of truth for local setup, run, and validation.
 - Node.js 18+
 - Rust toolchain (Tauri)
 - Docker + `docker compose`
+- Poetry 1.8.x
 
-## Install Poetry (pipx, PEP 668-safe)
-
-On macOS with Homebrew Python, install Poetry via `pipx`:
+Install Poetry with `pipx` on macOS/Homebrew Python:
 
 ```bash
 brew install pipx
@@ -23,19 +22,44 @@ poetry --version
 
 If `poetry` is not on your PATH yet, restart your shell.
 
+## Getting Started
+
+The deterministic beginner path is:
+
+```bash
+git clone <repo-url>
+cd SentinelID
+make install-dev
+cp .env.example .env
+make demo-up
+make demo-verify
+DEMO_AUTO_CLOSE_SECONDS=30 make demo
+make demo-down
+```
+
+What this does:
+
+- `make install-dev` installs edge, desktop, and admin dependencies from lockfiles.
+- `cp .env.example .env` gives you a dev-safe local config with matching admin credentials (`admin` / `admin123!`) and no manual secret generation.
+- `make demo-up` starts postgres, cloud, and admin and waits for health.
+- `make demo-verify` checks the non-interactive beginner path and is the canonical CI/headless command.
+- `make demo` launches the desktop flow for the interactive walkthrough. Use `DEMO_AUTO_CLOSE_SECONDS` when you want a scripted close.
+- `make demo-down` tears down the stack.
+
+If you only want the non-interactive validation path, stop after `make demo-verify` and run `make demo-down`.
+
 ## Environment
 
 ```bash
 cp .env.example .env
 ```
 
-Required values:
+`.env.example` is intentionally runnable for local development. Copy it as-is unless you are testing a non-default configuration.
+
+Canonical environment names:
 
-- `EDGE_AUTH_TOKEN`
-- `ADMIN_API_TOKEN`
-- `ADMIN_UI_USERNAME`
-- `ADMIN_UI_PASSWORD_HASH` (bcrypt hash for non-Docker runs; keep bcrypt values single-quoted in `.env`) or `ADMIN_UI_PASSWORD_HASH_B64` (recommended for Docker Compose)
-- `ADMIN_UI_SESSION_SECRET`
+- `ADMIN_API_TOKEN` is the source-of-truth admin credential in `.env`, Docker Compose, and docs.
+- `EDGE_AUTH_TOKEN` protects loopback admin/bearer endpoints on edge.
 - In `EDGE_ENV=prod`, device and master-key initialization require OS keychain access by default. Use `ALLOW_KEYCHAIN_FALLBACK=1` only for controlled debugging when fallback storage is unavoidable.
 
 Optional values:
@@ -68,10 +92,10 @@ Optional verification fallback toggle (dev only):
 
 ## Dependency Installation
 
+Use the canonical setup command:
+
 ```bash
-cd apps/edge && poetry install && cd ../..
-cd apps/desktop && npm install && cd ../..
-cd apps/admin && npm install && cd ../..
+make install-dev
 ```
 
 Important:
@@ -112,12 +136,14 @@ alembic revision --autogenerate -m "describe schema change"
 
 If you use local cloud runtime without Docker, run `alembic upgrade head` before starting uvicorn.
 
-## Recommended Local Run (3 Terminals)
+## Advanced Split-Terminal Workflow
+
+Use this only when you intentionally want the services and desktop in separate shells after the beginner path is already working.
 
-Terminal 1: Cloud + Admin (Docker)
+Terminal 1: Cloud + Admin (Docker-first)
 
 ```bash
-docker compose up --build
+make demo-up
 ```
 
 Terminal 2: Edge API (loopback-only)
@@ -161,7 +187,7 @@ make demo-down
 make demo-down V=1
 ```
 
-## Desktop UX (v2.5.0)
+## Desktop UX (v2.6.0)
 
 Primary tabs in the desktop UI:
 
@@ -324,22 +350,22 @@ Mode behavior:
 Distribution smoke:
 
 ```bash
-./scripts/smoke_test_bundling.sh
+make smoke-bundling
 ```
 
-Optional local sanity check for "no Poetry at runtime" path:
+Optional local sanity check for the bundled runtime path:
 
 ```bash
-PATH="/usr/bin:/bin:/usr/sbin:/sbin" SKIP_DESKTOP_BUILD=1 ./scripts/smoke_test_bundling.sh
+SKIP_DESKTOP_BUILD=1 make smoke-bundling
 ```
 
 ## Support Bundle (Sanitized)
 
 Generate a support/debug bundle without raw frames, embeddings, tokens, or signatures:
 
 ```bash
-EDGE_TOKEN="${EDGE_AUTH_TOKEN}" ADMIN_TOKEN="${ADMIN_API_TOKEN}" ./scripts/support_bundle.sh
-./scripts/check_local_support_bundle_sanitization.sh
+EDGE_AUTH_TOKEN="${EDGE_AUTH_TOKEN}" ADMIN_API_TOKEN="${ADMIN_API_TOKEN}" make support-bundle
+make check-local-support-bundle
 ```
 
 Artifact path:

apps/cloud/main.py

@@ -89,7 +89,7 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(
     title="SentinelID Cloud",
-    version="2.5.0",
+    version="2.6.0",
     lifespan=lifespan,
 )
 

apps/cloud/tests/test_release_docs_consistency.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+DOCS_CONSISTENCY_SCRIPT = REPO_ROOT / "scripts" / "release" / "check_docs_consistency.sh"
+FRESH_CLONE_SCRIPT = REPO_ROOT / "scripts" / "check_fresh_clone_bootstrap.sh"
+
+
+def test_docs_root_has_no_phase_markdown_files() -> None:
+    docs_root = REPO_ROOT / "docs"
+    phase_files = sorted(path.name for path in docs_root.glob("phase*.md"))
+    assert phase_files == []
+
+
+def test_docs_consistency_script_passes() -> None:
+    result = subprocess.run(
+        [str(DOCS_CONSISTENCY_SCRIPT)],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stderr or result.stdout
+    assert "Docs consistency check passed" in result.stdout
+
+
+def test_docs_consistency_script_passes_without_rg() -> None:
+    env = {"PATH": "/usr/bin:/bin:/usr/sbin:/sbin"}
+    result = subprocess.run(
+        [str(DOCS_CONSISTENCY_SCRIPT)],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+        env=env,
+    )
+
+    assert result.returncode == 0, result.stderr or result.stdout
+    assert "Docs consistency check passed" in result.stdout
+
+
+def test_fresh_clone_bootstrap_dry_run_uses_canonical_make_targets() -> None:
+    result = subprocess.run(
+        [str(FRESH_CLONE_SCRIPT), "--dry-run"],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stderr or result.stdout
+    assert "install lockfile-managed dev dependencies" in result.stdout
+    assert "install-dev" in result.stdout
+    assert "demo-up" in result.stdout
+    assert "demo-verify" in result.stdout
+    assert "demo-down" in result.stdout
+
+
+def test_docs_consistency_requires_full_command_tokens() -> None:
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        root = Path(tmp_dir)
+        (root / "docs").mkdir()
+        (root / "RUNBOOK.md").write_text(
+            "\n".join(
+                [
+                    "make install-dev",
+                    "make demo-up",
+                    "make demo-verify",
+                    "make demo-up",
+                    "make demo-down",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        (root / "docs" / "RELEASE.md").write_text(
+            "\n".join(
+                [
+                    "make release-check",
+                    "make check-version-consistency",
+                    "make check-docs-consistency",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        (root / "docs" / "PACKAGING.md").write_text(
+            "\n".join(
+                [
+                    "make bundle-edge",
+                    "make build-desktop-web",
+                    "make smoke-bundling",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        (root / "docs" / "RECOVERY.md").write_text(
+            "\n".join(["make smoke-cloud-recovery", "make support-bundle"]),
+            encoding="utf-8",
+        )
+        (root / "docs" / "DEMO_CHECKLIST.md").write_text("make demo-up\n", encoding="utf-8")
+
+        env = {
+            "PATH": "/usr/bin:/bin:/usr/sbin:/sbin",
+            "DOCS_CONSISTENCY_ROOT_DIR": str(root),
+            "DOCS_CONSISTENCY_DOCS": "RUNBOOK.md docs/RELEASE.md docs/PACKAGING.md docs/RECOVERY.md docs/DEMO_CHECKLIST.md",
+        }
+        result = subprocess.run(
+            [str(DOCS_CONSISTENCY_SCRIPT)],
+            cwd=REPO_ROOT,
+            capture_output=True,
+            text=True,
+            check=False,
+            env=env,
+        )
+
+        assert result.returncode == 1
+        assert "Missing required docs guidance in RUNBOOK.md: make demo" in result.stdout
+        assert "Missing required docs guidance in docs/PACKAGING.md: make build-desktop" in result.stdout