@mriekki/lean 0.4.5 → 0.4.7

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
+      "commit": "c53620078d22ec8acb6fee99006045736a2d6491",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
+      "commit": "a4cdb4f43982692536b669a135a4c81057368fce",
       "distribution": "greenfield-poc",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -20,6 +20,7 @@
     {"source":"core/skills/core-sync/SKILL.md","destination":".github/skills/core-sync/SKILL.md"},
     {"source":"core/skills/upstream-fix/SKILL.md","destination":".github/skills/upstream-fix/SKILL.md"},
     {"source":"core/skills/wait-what/SKILL.md","destination":".github/skills/wait-what/SKILL.md"},
+    {"source":"core/skills/developer-env-mode/SKILL.md","destination":".github/skills/developer-env-mode/SKILL.md"},
     {"source":"core/skills/deployment-readiness/SKILL.md","destination":".github/skills/deployment-readiness/SKILL.md"},
     {"source":"core/skills/deploy/SKILL.md","destination":".github/skills/deploy/SKILL.md"},
     {"source":"core/skills/tear-down/SKILL.md","destination":".github/skills/tear-down/SKILL.md"},

package/assets/deployment/distribution.json

@@ -11,6 +11,8 @@
     {"source": "src/lean_poc_deployment/app_runtime_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime_remote.py"},
     {"source": "src/lean_poc_deployment/local_cli.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py"},
     {"source": "src/lean_poc_deployment/local_runtime.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py"},
+    {"source": "src/lean_poc_deployment/local_spec.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_spec.py"},
+    {"source": "src/lean_poc_deployment/local_sqlite.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_sqlite.py"},
     {"source": "src/lean_poc_deployment/box_platform.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py"},
     {"source": "src/lean_poc_deployment/box_platform_assets.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_assets.py"},
     {"source": "src/lean_poc_deployment/box_platform_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_remote.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
+      "commit": "c53620078d22ec8acb6fee99006045736a2d6491",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -99,6 +99,11 @@
           "destination": ".github/skills/wait-what/SKILL.md",
           "sha256": "9b5968158992681837071b60465682a887540b1fdab510861ed739ffa996fbdb"
         },
+        {
+          "source": "core/skills/developer-env-mode/SKILL.md",
+          "destination": ".github/skills/developer-env-mode/SKILL.md",
+          "sha256": "23a026a3c2e999855fe64006e76bffcbecf6348696266fd94452c605ef1d4c03"
+        },
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
@@ -192,7 +197,7 @@
         {
           "source": "core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
           "destination": "docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
-          "sha256": "e6697c8d9bc346e8c8229625fc422b869a6428a083e4fee717b97d17afde7b03"
+          "sha256": "8dc0773a245ed23089caa02a1a2f0dd5670710646d446d190406ae47a85da4c6"
         },
         {
           "source": "core/process/LEAN_ENGINEERING_GUIDE.md",
@@ -282,7 +287,7 @@
         {
           "source": "tools/docs_site/docs_site.py",
           "destination": "tools/lean-docs/docs-site.py",
-          "sha256": "d8516175150b48b85b2a0b8013d5790b78bdd6eb6de73ab8dce9ed8e32e2dc68"
+          "sha256": "50ea30f5d42f71176a74a642123089c6e246f2da616e0c0bba2f16168d2c15c9"
         },
         {
           "source": "tools/package/check_baseline.py",
@@ -298,7 +303,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
+      "commit": "a4cdb4f43982692536b669a135a4c81057368fce",
       "distribution": "greenfield-poc",
       "files": [
         {
@@ -334,13 +339,23 @@
         {
           "source": "src/lean_poc_deployment/local_cli.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py",
-          "sha256": "9c658c0409da3c6297ad349035bccb263a587cd6d9b07a9796ccbb7cdb6676f9"
+          "sha256": "b183d937b21cef10c4766d588dccd03a729a373e587a82e7b80a9e2390797eb9"
         },
         {
           "source": "src/lean_poc_deployment/local_runtime.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py",
           "sha256": "82cf795733b59f4591515396be65317da4e515fde19874e3c5851bcff412d84d"
         },
+        {
+          "source": "src/lean_poc_deployment/local_spec.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_spec.py",
+          "sha256": "372b8c041edd9d3a1005861d85bb3a6bad38064b0be081a470460ad2dc62be4d"
+        },
+        {
+          "source": "src/lean_poc_deployment/local_sqlite.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_sqlite.py",
+          "sha256": "767c91f2af1f0df6f88b81a867826e4beaa1871865a97a9002a6b3fc53c781c9"
+        },
         {
           "source": "src/lean_poc_deployment/box_platform.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py",

package/assets/generated/core/core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md

@@ -190,6 +190,8 @@ Build-only mode:
 python .\tools\lean-docs\docs-site.py build --root . --out .\.lean\docs-site
 ```
 
+The builder protects existing data: it refuses the repository root, paths overlapping either lab cache, linked paths, and non-empty output directories without its `.lean-docs-site` ownership marker. Existing unmarked output from an older viewer must be inspected and moved or a new output path selected before rebuilding.
+
 The viewer should:
 
 - bind to loopback only;

package/assets/generated/core/core/skills/developer-env-mode/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: developer-env-mode
+description: "Converge and verify the developer workstation for local-only or remote-enabled work. Mode changes become effective only after the selected readiness contract passes."
+argument-hint: "status|local|remote"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Developer Environment Mode
+
+`/developer-env-mode` manages the current workstation's operational development mode. It is not a deployment command and it does not weaken Staging or Production gates.
+
+Supported intents:
+
+```text
+/developer-env-mode status
+/developer-env-mode local
+/developer-env-mode remote
+```
+
+The governing invariant is:
+
+```text
+MODE != preference
+MODE = verified operational state
+```
+
+Never record a requested mode as ready until its readiness contract passes. If convergence fails, preserve the prior ready mode when one exists and report the blocker.
+
+## 1. Resolve repository and package provenance read-only
+
+From the repository root inspect, when present:
+
+- `POC_BOOTSTRAP.json`;
+- `LEAN_BASELINE.json` and component baselines;
+- `DEV_ENVIRONMENT.json`;
+- application setup/build/test commands and project-owned persistence configuration;
+- deployment topology and generated deployment tooling;
+- Git status so unrelated work is preserved.
+
+For package-managed consumers, verify managed files are coherent before relying on distributed Core or Deployment tooling. Route managed drift to `/lean-update` rather than overwriting it.
+
+Do not require a Bootstrap/Core/Deployment Kit source checkout for normal consumer use.
+
+## 2. Keep current mode state workstation-local
+
+Mode state is user/workstation state, not repository authority. Store it outside the repository under the user-scoped Lean directory, using a repository-scoped location such as:
+
+```text
+~/.lean-poc/workspaces/<owner>/<repo>/developer-environment.json
+```
+
+Do not commit this state. Do not store credentials, private keys, target trust stores, database contents, or secret values in it.
+
+Record enough non-secret evidence to distinguish requested mode from readiness, for example:
+
+- mode;
+- ready/not-ready;
+- verification timestamp;
+- source revision when available;
+- build/test state or fingerprint;
+- local database state when applicable;
+- local runtime health when applicable;
+- remote target/access readiness summary when applicable.
+
+A later `status` check must be allowed to report that the recorded mode is no longer ready when Docker stops, tools drift, the build becomes stale, the local database is missing/incompatible, or remote access disappears.
+
+## 3. `status` is read-only
+
+`/developer-env-mode status` performs no setup writes. Inspect current workstation evidence and live prerequisites, then report both the selected mode and current readiness.
+
+Prefer a compact result such as:
+
+```text
+DEVELOPER ENVIRONMENT
+
+Selected mode: LOCAL
+Readiness: NOT READY
+
+Docker ........ READY
+Build ......... STALE
+Tests ......... READY
+SQLite ........ READY
+Runtime ....... HEALTHY
+Remote access . UNAVAILABLE
+
+NEXT
+/developer-env-mode local
+```
+
+Do not silently repair state during `status`.
+
+## 4. `local` means converge a complete local development environment
+
+Selecting `local` authorizes bounded, non-destructive workstation setup needed to make the current repository usable locally. It does not authorize destructive database reset, deletion of unrelated Docker state, remote publication, remote deployment, or Production writes.
+
+Converge in this order.
+
+### A. Workstation prerequisites
+
+Verify the current OS is supported by repository configuration. Use repository setup/doctor tooling when present to verify required tools and versions.
+
+For Docker-based local execution require a working Docker CLI/engine. Prefer repository-distributed Deployment Kit commands when `DEPLOYMENT_BASELINE.json` proves they are installed.
+
+### B. Dependencies and restore
+
+Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions. Do not substitute arbitrary global tooling when the repository defines a supported path.
+
+### C. Local persistence
+
+If the application uses SQLite for local development:
+
+1. resolve the project-owned database filename/container path and migration/initialization contract from repository configuration/docs/code;
+2. prefer the installed Deployment Kit local SQLite ensure/status primitive when available for workstation-owned persistent storage;
+3. when the database is absent, create the owned local SQLite file/directory non-destructively;
+4. run the repository-provided migration/schema initialization needed to make that database usable;
+5. verify the resulting database can be opened and that the application-required schema/migration state is current when the repository provides such a check.
+
+If an existing SQLite database is corrupt, incompatible, or has unexpected ownership/schema state, **STOP**. Never delete, replace, reset, or migrate destructively merely to make mode convergence pass. Present the exact recovery/reset decision separately.
+
+Do not assume every project uses SQLite. Other persistence requires an explicit repository-owned local setup contract.
+
+### D. Build and tests
+
+Run the repository's required local build and test commands. A missing or stale build is a normal convergence condition; rebuild it.
+
+If build or required tests fail, report `LOCAL MODE NOT READY` and do not mark the mode ready.
+
+When the project policy says application validation is local-only, GitHub publication/PR activity does not replace this local build/test evidence.
+
+### E. Local immutable Docker artifact
+
+When the local runtime is Docker-based, build the application image locally using repository-owned commands. Resolve an immutable local image identity.
+
+The standard Deployment Kit workstation adapter may accept either:
+
+- an exact registry digest (`name@sha256:...`), or
+- a local Docker image ID (`sha256:<64 hex>`) for workstation-only execution.
+
+Never use a mutable tag as the final deployed identity. A local image ID is valid only for workstation placement and is not remote-release evidence.
+
+### F. Workstation runtime
+
+Converge the local application runtime through the repository-distributed workstation adapter when available:
+
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+```
+
+Keep exposure loopback-only. Mount the project-owned local SQLite persistence directory when required. Verify the declared health endpoint and any required local smoke check.
+
+Do not resolve SSH targets, publish images, create public routes, or deploy Staging/Production while entering local mode.
+
+### G. Commit local mode only after readiness passes
+
+Only after prerequisites, persistence, build, tests, runtime, and health requirements pass, write the workstation-local mode state as ready.
+
+A successful summary should distinguish local evidence from remote evidence:
+
+```text
+LOCAL DEVELOPER ENVIRONMENT READY
+
+Build ........ READY
+Tests ........ READY
+Docker ....... READY
+SQLite ....... READY / NOT APPLICABLE
+Application .. HEALTHY
+Remote deploy. DISABLED BY MODE
+```
+
+## 5. `remote` means verify remote-enabled capability, not deploy
+
+Selecting `remote` authorizes bounded, non-destructive checks/setup needed to prove that the current workstation can work with the repository's configured remote non-Production environment(s). It does **not** publish an artifact or deploy an application.
+
+Verify as applicable:
+
+- normal local developer prerequisites still needed to build/test the project;
+- repository deployment topology contains a non-deferred remote environment;
+- exact target/provider binding exists when required;
+- workstation-to-target trust/access is valid;
+- target OS/runtime/platform readiness is valid;
+- persistence/readiness prerequisites can be inspected safely;
+- GitHub/registry access needed for a later release/publish step is available;
+- repository release/deployment tooling and baselines are coherent.
+
+For the standard remote-SSH path preserve strict host identity. Unknown or changed host identity is a stop condition. Never fall back to another environment or host.
+
+Do not require a Production target merely to enter remote mode. Do not weaken Production authorization because remote mode is ready.
+
+Only after the selected remote readiness checks pass, record `remote` as ready.
+
+Then report the next explicit operation, typically:
+
+```text
+/deployment-readiness <environment>
+```
+
+A later `/deploy <environment>` remains separately gated.
+
+## 6. Fail closed on destructive or ambiguous repair
+
+Automatic convergence may safely create missing local directories, dependency caches, build outputs, a new owned SQLite file, migrations that the project defines as normal forward initialization, and a new owned local application container.
+
+Stop for a separate explicit decision before:
+
+- deleting/resetting an existing database;
+- destructive migration or rollback;
+- replacing unexplained persistent data;
+- deleting unrelated containers/images/volumes;
+- publishing an artifact remotely;
+- rebinding a target;
+- weakening host verification;
+- deploying Staging or Production;
+- changing public/LAN exposure.
+
+## 7. Relationship to other Lean commands
+
+`/developer-env-mode` prepares a workstation and establishes current operational readiness.
+
+It does not replace:
+
+- `/lean-update` for managed Lean package changes;
+- project setup/doctor tooling;
+- `/start-work` for implementation authorization;
+- `/deployment-readiness` for environment-specific pre-deploy evidence;
+- `/deploy` for deployment authorization/execution;
+- `/tear-down` for destructive cleanup.
+
+Mode switching never implies merge, release publication, Staging deployment, or Production deployment.

package/assets/generated/core/tools/docs_site/docs_site.py

@@ -13,13 +13,15 @@ import webbrowser
 from datetime import datetime, timezone
 from functools import partial
 from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
-from pathlib import Path
+from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Any
 
 IGNORE_DIRS = {".git", ".lean", "node_modules", "bin", "obj", "dist", "build", "target", ".venv", "venv", "__pycache__"}
 DEFAULT_CACHE = Path(".lean/docs-cache")
 DEFAULT_SITE = Path(".lean/docs-site")
 MANIFEST = Path("docs/lean-docs.json")
+SITE_MARKER = ".lean-docs-site"
+SITE_MARKER_CONTENT = "lean-docs-site\n"
 
 
 class DocsSiteError(RuntimeError):
@@ -86,17 +88,30 @@ def _manifest_documents(root: Path, manifest: dict[str, Any] | None) -> tuple[li
             if not isinstance(item, dict) or not isinstance(item.get("path"), str):
                 warnings.append(f"docs/lean-docs.json documents[{index}] is invalid")
                 continue
-            rel = Path(item["path"]).as_posix().lstrip("/")
-            if rel.startswith("../") or "/../" in rel:
+            raw_path = item["path"]
+            windows_path = PureWindowsPath(raw_path)
+            relative_path = PurePosixPath(raw_path.replace("\\", "/"))
+            if (
+                relative_path.is_absolute()
+                or windows_path.root
+                or windows_path.drive
+                or ".." in relative_path.parts
+            ):
                 warnings.append(f"Skipped unsafe documentation path: {item['path']}")
                 continue
+            rel = relative_path.as_posix()
             path = root / rel
+            try:
+                resolved_path = root / _safe_rel(root, path)
+            except DocsSiteError:
+                warnings.append(f"Skipped unsafe documentation path: {item['path']}")
+                continue
             seen.add(rel)
-            if not path.is_file():
+            if not resolved_path.is_file():
                 if item.get("optional") is not True:
                     warnings.append(f"Listed documentation is not present: {rel}")
                 continue
-            content = path.read_text(encoding="utf-8", errors="replace")
+            content = resolved_path.read_text(encoding="utf-8", errors="replace")
             docs.append(
                 {
                     "path": rel,
@@ -116,14 +131,30 @@ def _manifest_documents(root: Path, manifest: dict[str, Any] | None) -> tuple[li
             candidates.append(path)
     docs_root = root / "docs"
     if docs_root.is_dir():
-        for base, dirs, names in os.walk(docs_root):
-            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
-            for name in names:
-                if name.lower().endswith(".md"):
-                    candidates.append(Path(base) / name)
+        if _path_contains_link(docs_root):
+            warnings.append(f"Skipped unsafe documentation directory: {docs_root}")
+        else:
+            for base, dirs, names in os.walk(docs_root):
+                safe_dirs = []
+                for directory in dirs:
+                    candidate = Path(base) / directory
+                    if directory in IGNORE_DIRS:
+                        continue
+                    if _is_link(candidate):
+                        warnings.append(f"Skipped unsafe documentation directory: {candidate}")
+                        continue
+                    safe_dirs.append(directory)
+                dirs[:] = safe_dirs
+                for name in names:
+                    if name.lower().endswith(".md"):
+                        candidates.append(Path(base) / name)
 
     for path in sorted(candidates):
-        rel = _safe_rel(root, path)
+        try:
+            rel = _safe_rel(root, path)
+        except DocsSiteError:
+            warnings.append(f"Skipped unsafe documentation path: {path}")
+            continue
         if rel in seen:
             continue
         content = path.read_text(encoding="utf-8", errors="replace")
@@ -220,14 +251,113 @@ def _prepare_system_lab(root: Path) -> str | None:
     return None
 
 
-def _copy_lab_cache(root: Path, out: Path, kind: str) -> None:
+def _validate_lab_cache(root: Path, kind: str) -> Path:
     source = root / DEFAULT_CACHE / kind
-    if not source.is_dir():
-        return
+    if _path_contains_link(source):
+        raise DocsSiteError(f"Lab cache contains a symlink or junction: {source}")
+    if source.exists():
+        try:
+            source.resolve().relative_to(root)
+        except ValueError as exc:
+            raise DocsSiteError(f"Lab cache escapes repository root: {source}") from exc
+    if source.is_dir() and _directory_contains_link(source):
+        raise DocsSiteError(f"Lab cache contains a symlink or junction: {source}")
+    return source
+
+
+def _copy_lab_cache(root: Path, out: Path, kind: str) -> None:
+    source = _validate_lab_cache(root, kind)
     target = out / "labs" / kind
+    try:
+        target.resolve().relative_to(out)
+    except ValueError as exc:
+        raise DocsSiteError(f"Lab output escapes generated site directory: {target}") from exc
+    if _path_contains_link(target):
+        raise DocsSiteError(f"Lab output contains a symlink or junction: {target}")
     if target.exists():
+        if target.is_symlink() or not target.is_dir():
+            raise DocsSiteError(f"Unexpected lab output path: {target}")
         shutil.rmtree(target)
-    shutil.copytree(source, target)
+    if source.is_dir():
+        shutil.copytree(source, target)
+
+
+def _is_link(path: Path) -> bool:
+    if path.is_symlink():
+        return True
+    is_junction = getattr(path, "is_junction", None)
+    return bool(is_junction and is_junction())
+
+
+def _path_contains_link(path: Path) -> bool:
+    absolute = Path(os.path.abspath(path))
+    current = Path(absolute.anchor)
+    for part in absolute.parts[1:]:
+        current /= part
+        if _is_link(current):
+            return True
+    return False
+
+
+def _paths_overlap(left: Path, right: Path) -> bool:
+    left = Path(os.path.abspath(left))
+    right = Path(os.path.abspath(right))
+    return left == right or left in right.parents or right in left.parents
+
+
+def _directory_contains_link(root: Path) -> bool:
+    directories = [root]
+    while directories:
+        current = directories.pop()
+        with os.scandir(current) as entries:
+            for entry in entries:
+                path = Path(entry.path)
+                if _is_link(path):
+                    return True
+                if entry.is_dir(follow_symlinks=False):
+                    directories.append(path)
+    return False
+
+
+def _prepare_output(root: Path, out: Path) -> None:
+    if _path_contains_link(out):
+        raise DocsSiteError(f"Refusing to use an output path containing a symlink or junction: {out}")
+    if out == root or out in root.parents:
+        raise DocsSiteError(f"Refusing to use the repository root or one of its parents as output: {out}")
+    for kind in ("system", "database"):
+        cache = root / DEFAULT_CACHE / kind
+        if _paths_overlap(out, cache):
+            raise DocsSiteError(f"Output path overlaps a lab cache: {cache}")
+
+    if out.exists():
+        if not out.is_dir():
+            raise DocsSiteError(f"Output path is not a directory: {out}")
+        marker = out / SITE_MARKER
+        if any(out.iterdir()):
+            if marker.is_symlink() or not marker.is_file():
+                raise DocsSiteError(f"Refusing to overwrite an unowned output directory: {out}")
+            try:
+                marker_content = marker.read_text(encoding="utf-8")
+            except OSError as exc:
+                raise DocsSiteError(f"Unable to verify output ownership: {marker}") from exc
+            if marker_content != SITE_MARKER_CONTENT:
+                raise DocsSiteError(f"Refusing to overwrite an unowned output directory: {out}")
+
+        if _directory_contains_link(out):
+            raise DocsSiteError(f"Refusing to write through a symlink in output directory: {out}")
+
+        for name in (SITE_MARKER, "index.html", "site.json"):
+            path = out / name
+            if path.is_file():
+                try:
+                    link_count = path.stat().st_nlink
+                except OSError as exc:
+                    raise DocsSiteError(f"Unable to verify output file links: {path}") from exc
+                if link_count > 1:
+                    raise DocsSiteError(f"Refusing to overwrite hard-linked output file: {path}")
+
+    out.mkdir(parents=True, exist_ok=True)
+    (out / SITE_MARKER).write_text(SITE_MARKER_CONTENT, encoding="utf-8")
 
 
 def _site_payload(root: Path) -> dict[str, Any]:
@@ -299,16 +429,16 @@ document.querySelector('#siteTitle').textContent=SITE.title;document.querySelect
 
 def build(root: Path, out: Path, *, prepare_system_lab: bool = False) -> tuple[Path, dict[str, Any]]:
     root = root.resolve()
-    out = out.resolve()
+    out = Path(os.path.abspath(out))
     if not root.is_dir():
         raise DocsSiteError(f"Repository root does not exist: {root}")
+    for kind in ("system", "database"):
+        _validate_lab_cache(root, kind)
+    _prepare_output(root, out)
     prep_warning = _prepare_system_lab(root) if prepare_system_lab else None
     payload = _site_payload(root)
     if prep_warning:
         payload["warnings"].append(prep_warning)
-    if out.exists():
-        shutil.rmtree(out)
-    out.mkdir(parents=True, exist_ok=True)
     _copy_lab_cache(root, out, "system")
     _copy_lab_cache(root, out, "database")
     index = out / "index.html"
@@ -359,7 +489,7 @@ def parse_args() -> argparse.Namespace:
 def main() -> int:
     args = parse_args()
     root = args.root.resolve()
-    out = args.out.resolve() if args.out else (root / DEFAULT_SITE).resolve()
+    out = args.out if args.out else root / DEFAULT_SITE
     try:
         if args.command == "build":
             index, payload = build(root, out, prepare_system_lab=args.prepare_system_lab)

package/assets/generated/deployment/src/lean_poc_deployment/local_cli.py

@@ -12,9 +12,13 @@ from .local_runtime import (
     apply_local_deploy,
     local_deploy_write_phrase,
     local_inventory,
-    normalize_local_spec,
     plan_local_deploy,
 )
+from .local_spec import normalize_workstation_spec
+from .local_sqlite import ensure_local_sqlite, local_sqlite_status
+
+
+LOCAL_SQLITE_ENSURE_WRITE_PHRASE = "[LOCAL SQLITE ENSURE]"
 
 
 def _print(value: Any, *, as_json: bool) -> None:
@@ -45,6 +49,14 @@ def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
         raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
 
 
+def _add_sqlite_identity(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--owner-repo", required=True)
+    parser.add_argument("--environment", required=True)
+    parser.add_argument("--app-slug", required=True)
+    parser.add_argument("--database-file", required=True)
+    parser.add_argument("--json", action="store_true")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="lean-poc-deploy local")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -55,6 +67,19 @@ def build_parser() -> argparse.ArgumentParser:
     )
     inventory.add_argument("--json", action="store_true")
 
+    sqlite_status = sub.add_parser(
+        "sqlite-status",
+        help="Inspect one Lean-owned workstation SQLite database without writes",
+    )
+    _add_sqlite_identity(sqlite_status)
+
+    sqlite_ensure = sub.add_parser(
+        "sqlite-ensure",
+        help="Create a missing Lean-owned workstation SQLite database non-destructively",
+    )
+    _add_sqlite_identity(sqlite_ensure)
+    sqlite_ensure.add_argument("--yes", action="store_true")
+
     deploy = sub.add_parser(
         "deploy",
         help="Deploy one immutable application container bound only to loopback",
@@ -83,7 +108,50 @@ def main(argv: list[str] | None = None) -> int:
             _print(local_inventory(), as_json=args.json)
             return 0
 
-        spec = normalize_local_spec(
+        if args.command == "sqlite-status":
+            _print(
+                local_sqlite_status(
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    app_slug=args.app_slug,
+                    database_file=args.database_file,
+                ),
+                as_json=args.json,
+            )
+            return 0
+
+        if args.command == "sqlite-ensure":
+            status = local_sqlite_status(
+                owner_repo=args.owner_repo,
+                environment=args.environment,
+                app_slug=args.app_slug,
+                database_file=args.database_file,
+            )
+            if status["state"] == "ready":
+                _print(status, as_json=args.json)
+                return 0
+            if status["state"] == "unmanaged-existing":
+                raise DeploymentKitError(
+                    "Refusing automatic adoption of an existing unmanaged local SQLite database."
+                )
+            _print(status, as_json=False)
+            _confirm(
+                args,
+                LOCAL_SQLITE_ENSURE_WRITE_PHRASE,
+                f"create local SQLite storage for {args.app_slug} ({args.environment})",
+            )
+            _print(
+                ensure_local_sqlite(
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    app_slug=args.app_slug,
+                    database_file=args.database_file,
+                ),
+                as_json=args.json,
+            )
+            return 0
+
+        spec = normalize_workstation_spec(
             owner_repo=args.owner_repo,
             environment=args.environment,
             app_slug=args.app_slug,

package/assets/generated/deployment/src/lean_poc_deployment/local_spec.py

@@ -0,0 +1,82 @@
+"""Workstation-only application spec normalization."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Iterable
+
+from .app_runtime import normalize_app_spec
+from .errors import DeploymentKitError
+
+
+_LOCAL_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _host_port(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 65535:
+        raise DeploymentKitError("hostPort must be an integer from 1 through 65535.")
+    return value
+
+
+def _base_image(image: str) -> tuple[str, bool]:
+    if isinstance(image, str) and _LOCAL_IMAGE_ID_RE.fullmatch(image):
+        return f"local-workstation/immutable@{image}", True
+    return image, False
+
+
+def normalize_workstation_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    container_name: str,
+    image: str,
+    runtime_port: int,
+    host_port: int,
+    health_path: str,
+    run_as: str,
+    persistence_mode: str,
+    data_container_path: str | None,
+    environment_variables: dict[str, str] | Iterable[tuple[str, str]],
+) -> dict[str, Any]:
+    """Normalize a loopback-only workstation spec.
+
+    Remote deployment keeps the registry-digest-only contract. Workstation execution
+    additionally accepts an immutable local Docker image ID (sha256:<64 hex>) so a
+    developer can build/test/run without publishing to a registry first.
+    """
+
+    normalized_image, local_image_id = _base_image(image)
+    base = normalize_app_spec(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        container_name=container_name,
+        image=normalized_image,
+        runtime_port=runtime_port,
+        health_path=health_path,
+        run_as=run_as,
+        persistence_mode=persistence_mode,
+        data_container_path=data_container_path,
+        environment_variables=environment_variables,
+    )
+    base.pop("specSha256", None)
+    if local_image_id:
+        base["image"] = image
+    base.update(
+        {
+            "schemaVersion": 1,
+            "placement": "workstation",
+            "isolation": "container",
+            "exposure": "loopback",
+            "hostAddress": "127.0.0.1",
+            "hostPort": _host_port(host_port),
+            "imageSource": "local-image-id" if local_image_id else "registry-digest",
+        }
+    )
+    base["specSha256"] = hashlib.sha256(
+        json.dumps(base, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+    return base

package/assets/generated/deployment/src/lean_poc_deployment/local_sqlite.py

@@ -0,0 +1,205 @@
+"""Non-destructive workstation SQLite lifecycle helpers."""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .errors import DeploymentKitError
+from .profiles import config_root
+
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_DB_FILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_METADATA_FILE = "sqlite-local.json"
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _database_file(value: str) -> str:
+    if not isinstance(value, str) or _DB_FILE_RE.fullmatch(value) is None or value in {".", ".."}:
+        raise DeploymentKitError("databaseFile must be a safe file name without path separators.")
+    return value
+
+
+def _state_root(app_slug: str, environment: str) -> Path:
+    return config_root() / "local-apps" / app_slug / environment
+
+
+def _data_dir(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / "data"
+
+
+def _metadata_path(app_slug: str, environment: str) -> Path:
+    return _state_root(app_slug, environment) / _METADATA_FILE
+
+
+def _database_path(app_slug: str, environment: str, database_file: str) -> Path:
+    return _data_dir(app_slug, environment) / database_file
+
+
+def _load_metadata(app_slug: str, environment: str) -> dict[str, Any] | None:
+    path = _metadata_path(app_slug, environment)
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise DeploymentKitError(f"Cannot read local SQLite metadata {path}: {error}") from error
+    if not isinstance(value, dict) or value.get("schemaVersion") != 1:
+        raise DeploymentKitError(f"Unsupported local SQLite metadata: {path}")
+    return value
+
+
+def _write_metadata(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def _quick_check(path: Path) -> str:
+    try:
+        with sqlite3.connect(path) as connection:
+            row = connection.execute("PRAGMA quick_check").fetchone()
+    except sqlite3.DatabaseError as error:
+        raise DeploymentKitError(f"Local SQLite database is not valid: {path}: {error}") from error
+    result = str(row[0]) if row else "missing-result"
+    if result.lower() != "ok":
+        raise DeploymentKitError(f"Local SQLite quick_check failed for {path}: {result}")
+    return result
+
+
+def local_sqlite_status(
+    *, owner_repo: str, environment: str, app_slug: str, database_file: str
+) -> dict[str, Any]:
+    owner_repo = _owner_repo(owner_repo)
+    environment = _slug(environment, "environment")
+    app_slug = _slug(app_slug, "appSlug")
+    database_file = _database_file(database_file)
+    metadata = _load_metadata(app_slug, environment)
+    path = _database_path(app_slug, environment, database_file)
+
+    if metadata is not None:
+        expected = {
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+        }
+        for key, value in expected.items():
+            if metadata.get(key) != value:
+                raise DeploymentKitError(
+                    f"Local SQLite metadata ownership mismatch for {app_slug}/{environment}: {key}."
+                )
+
+    if path.exists() and metadata is None:
+        return {
+            "schemaVersion": 1,
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+            "databasePath": str(path),
+            "state": "unmanaged-existing",
+            "managed": False,
+            "present": True,
+            "valid": False,
+            "mutated": False,
+        }
+
+    if not path.exists():
+        return {
+            "schemaVersion": 1,
+            "ownerRepo": owner_repo,
+            "environment": environment,
+            "appSlug": app_slug,
+            "databaseFile": database_file,
+            "databasePath": str(path),
+            "state": "missing",
+            "managed": metadata is not None,
+            "present": False,
+            "valid": False,
+            "mutated": False,
+        }
+
+    _quick_check(path)
+    return {
+        "schemaVersion": 1,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "databaseFile": database_file,
+        "databasePath": str(path),
+        "state": "ready",
+        "managed": True,
+        "present": True,
+        "valid": True,
+        "bytes": path.stat().st_size,
+        "mutated": False,
+    }
+
+
+def ensure_local_sqlite(
+    *, owner_repo: str, environment: str, app_slug: str, database_file: str
+) -> dict[str, Any]:
+    owner_repo = _owner_repo(owner_repo)
+    environment = _slug(environment, "environment")
+    app_slug = _slug(app_slug, "appSlug")
+    database_file = _database_file(database_file)
+
+    status = local_sqlite_status(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        database_file=database_file,
+    )
+    if status["state"] == "unmanaged-existing":
+        raise DeploymentKitError(
+            "Refusing to adopt an existing unmanaged local SQLite database automatically. "
+            "Review its ownership/data before using or moving it."
+        )
+    if status["state"] == "ready":
+        return status
+
+    path = _database_path(app_slug, environment, database_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with sqlite3.connect(path) as connection:
+            connection.execute("PRAGMA user_version")
+            connection.commit()
+    except sqlite3.DatabaseError as error:
+        raise DeploymentKitError(f"Unable to create local SQLite database {path}: {error}") from error
+
+    metadata = {
+        "schemaVersion": 1,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "databaseFile": database_file,
+    }
+    _write_metadata(_metadata_path(app_slug, environment), metadata)
+    _quick_check(path)
+    result = local_sqlite_status(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        database_file=database_file,
+    )
+    result["mutated"] = True
+    result["created"] = True
+    return result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/lean",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Public consumer distribution and updater for Lean engineering assets.",
   "type": "module",
   "bin": {