@mriekki/lean 0.4.4 → 0.4.5

package/assets/components.json

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

package/assets/core/distribution.json

@@ -26,6 +26,7 @@
     {"source":"core/skills/coach/SKILL.md","destination":".github/skills/coach/SKILL.md"},
     {"source":"core/skills/db-lab/SKILL.md","destination":".github/skills/db-lab/SKILL.md"},
     {"source":"core/skills/system-lab/SKILL.md","destination":".github/skills/system-lab/SKILL.md"},
+    {"source":"core/skills/docs/SKILL.md","destination":".github/skills/docs/SKILL.md"},
     {"source":"core/skills/code-walkthrough/SKILL.md","destination":".github/skills/code-walkthrough/SKILL.md"},
     {"source":"core/skills/learning-review/SKILL.md","destination":".github/skills/learning-review/SKILL.md"},
     {"source":"core/process/WORK_ITEM_MODEL.md","destination":"docs/process/WORK_ITEM_MODEL.md"},
@@ -37,11 +38,14 @@
     {"source":"core/process/COACHING_GUIDE.md","destination":"docs/process/COACHING_GUIDE.md"},
     {"source":"core/process/DATABASE_LEARNING_WORKBENCH.md","destination":"docs/process/DATABASE_LEARNING_WORKBENCH.md"},
     {"source":"core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md","destination":"docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md"},
+    {"source":"core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md","destination":"docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md"},
+    {"source":"core/process/LEAN_ENGINEERING_GUIDE.md","destination":"docs/lean/LEAN_ENGINEERING_GUIDE.md"},
     {"source":"core/process/SETUP_ACCEPTANCE_CHECKLIST.md","destination":"docs/process/SETUP_ACCEPTANCE_CHECKLIST.md"},
     {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
     {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
     {"source":"core/templates/FEATURE_BRIEF_TEMPLATE.md","destination":"docs/templates/FEATURE_BRIEF_TEMPLATE.md"},
     {"source":"core/templates/REQUIREMENTS_TEMPLATE.md","destination":"docs/templates/REQUIREMENTS_TEMPLATE.md"},
+    {"source":"core/templates/ADR_TEMPLATE.md","destination":"docs/templates/ADR_TEMPLATE.md"},
     {"source":"core/learning/ENGINEERING_LEARNING_WORKBOOK.md","destination":"learning/ENGINEERING_LEARNING_WORKBOOK.md"},
     {"source":"core/learning/LEARNING_MAP.md","destination":"learning/LEARNING_MAP.md"},
     {"source":"core/learning/LEARNING_PROGRESS.md","destination":"learning/LEARNING_PROGRESS.md"},
@@ -52,6 +56,7 @@
     {"source":"core/learning/RESOURCE_CATALOG.md","destination":"learning/RESOURCE_CATALOG.md"},
     {"source":"tools/db_lab/sqlite_workbench.py","destination":"tools/lean-db-lab/sqlite-workbench.py"},
     {"source":"tools/system_lab/system_workbench.py","destination":"tools/lean-system-lab/system-workbench.py"},
+    {"source":"tools/docs_site/docs_site.py","destination":"tools/lean-docs/docs-site.py"},
     {"source":"tools/package/check_baseline.py","destination":"tools/lean-core/check-core-baseline.py"},
     {"source":"tools/package/check_upstream.py","destination":"tools/lean-core/check-core-upstream.py"}
   ]

package/assets/deployment/distribution.json

@@ -9,6 +9,8 @@
     {"source": "src/lean_poc_deployment/app_cli.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_cli.py"},
     {"source": "src/lean_poc_deployment/app_runtime.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime.py"},
     {"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/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.4",
+  "version": "0.4.5",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "c2d9538cdbb5ddb46527133fefae698e25a6e603",
+      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -27,12 +27,12 @@
         {
           "source": "core/instructions/lean-workflow.instructions.md",
           "destination": ".github/instructions/lean-workflow.instructions.md",
-          "sha256": "398b4734db1af4139e8395fc30dddd3fd45aaa76b4f5c5ce9c4b286c456d9430"
+          "sha256": "5f82d6709ad5382235bc83efdfdb031d1b97ff1050fa476db81c7753c8140054"
         },
         {
           "source": "core/instructions/lean-docs.instructions.md",
           "destination": ".github/instructions/lean-docs.instructions.md",
-          "sha256": "9d2d596fb9fc6c6f8afcc68ca6e4c94b2c50b396f3d970ef26797ae51cb03202"
+          "sha256": "f8b73ec5ae1e12fdd98db4ee2c404b0b770e78248bfadc827d00eefda4d5eaf5"
         },
         {
           "source": "core/skills/define-feature/SKILL.md",
@@ -62,7 +62,7 @@
         {
           "source": "core/skills/next-step/SKILL.md",
           "destination": ".github/skills/next-step/SKILL.md",
-          "sha256": "833b015a795dee2fa8eaefd8b7ea7dda42951390846cf3bc8c2c2eb2ea3451bf"
+          "sha256": "94a7b7c0ec56a1772439dd0fc9b7adec1d48a67978c2bce5ab0cbe88d7ef74f0"
         },
         {
           "source": "core/skills/deliver/SKILL.md",
@@ -102,17 +102,17 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "02a58ae52cab8b6b11734a8d4217bf7f7c9b11bcd7b35e4a2e16dfb8af8bce34"
+          "sha256": "411fa4c918715679afc8636bd0e6503c1427688af213bd37cea4ba4920a678db"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "259c0091672d79b7bc799f92cb21a4143af2951a4f2556794263237dfb7e7d7b"
+          "sha256": "3a118753fba9f3e529062b98adfba4df5e76842027421a75f4beeac9d6bc247b"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
           "destination": ".github/skills/tear-down/SKILL.md",
-          "sha256": "8826be8f97c5dab673c050c5ae7f959c5959871c401b0b3b7e6869660e669d93"
+          "sha256": "ac9dca37648dbd7ee1fa3b7117d136628cce5f8293a2c15d64f2ebcb8e788692"
         },
         {
           "source": "core/skills/coach/SKILL.md",
@@ -129,6 +129,11 @@
           "destination": ".github/skills/system-lab/SKILL.md",
           "sha256": "1ec8c3f46cca6e2e72be1a85aae1adad0c32872e531d80baf12b1e49f2b780fc"
         },
+        {
+          "source": "core/skills/docs/SKILL.md",
+          "destination": ".github/skills/docs/SKILL.md",
+          "sha256": "6edc48f28394ca99ea0e2a2abfa46901896199717a7a6b071028a43e56f327b7"
+        },
         {
           "source": "core/skills/code-walkthrough/SKILL.md",
           "destination": ".github/skills/code-walkthrough/SKILL.md",
@@ -152,7 +157,7 @@
         {
           "source": "core/process/DEPLOYMENT_ENABLEMENT.md",
           "destination": "docs/process/DEPLOYMENT_ENABLEMENT.md",
-          "sha256": "3b59c5984ecb51ac48efb40e7e2e24c1971db947d6eefa5dc3671254ca984af7"
+          "sha256": "987f6e68a2ab58d23388127fae2318b385ef86de389fc616c1e40b48c0ff3b07"
         },
         {
           "source": "core/process/HUMAN_GATES.md",
@@ -184,6 +189,16 @@
           "destination": "docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md",
           "sha256": "eb0f613717d6bfdaecbb9d3a8ecb6323fa27331e429f5c5781c5c5a0289a8091"
         },
+        {
+          "source": "core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
+          "destination": "docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
+          "sha256": "e6697c8d9bc346e8c8229625fc422b869a6428a083e4fee717b97d17afde7b03"
+        },
+        {
+          "source": "core/process/LEAN_ENGINEERING_GUIDE.md",
+          "destination": "docs/lean/LEAN_ENGINEERING_GUIDE.md",
+          "sha256": "85e18e8c00bfab8e05e9e5dbea0a74238b345d08634cf459ae2c3efe455e311a"
+        },
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
           "destination": "docs/process/SETUP_ACCEPTANCE_CHECKLIST.md",
@@ -209,6 +224,11 @@
           "destination": "docs/templates/REQUIREMENTS_TEMPLATE.md",
           "sha256": "ec85cc723071edb01f09acca41e20e9833afe21d06d103b39dfcdbfb59a31aed"
         },
+        {
+          "source": "core/templates/ADR_TEMPLATE.md",
+          "destination": "docs/templates/ADR_TEMPLATE.md",
+          "sha256": "f802ae066438642de9a4948980a4ab48c4cb68309fa5de16d48b08415a1a31fb"
+        },
         {
           "source": "core/learning/ENGINEERING_LEARNING_WORKBOOK.md",
           "destination": "learning/ENGINEERING_LEARNING_WORKBOOK.md",
@@ -259,6 +279,11 @@
           "destination": "tools/lean-system-lab/system-workbench.py",
           "sha256": "25b507bacb05b938bee299bcb44a5476a6fc5ecb9143f5561773adc7ff987fcc"
         },
+        {
+          "source": "tools/docs_site/docs_site.py",
+          "destination": "tools/lean-docs/docs-site.py",
+          "sha256": "d8516175150b48b85b2a0b8013d5790b78bdd6eb6de73ab8dce9ed8e32e2dc68"
+        },
         {
           "source": "tools/package/check_baseline.py",
           "destination": "tools/lean-core/check-core-baseline.py",
@@ -273,7 +298,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "2763e604c20e64720d7de71fa93a88d99677be36",
+      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
       "distribution": "greenfield-poc",
       "files": [
         {
@@ -306,6 +331,16 @@
           "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime_remote.py",
           "sha256": "f3ccde6ed3c6e5fe185a9a0f032a5c924fa0906e3619e12d0ad6228c1210f8ec"
         },
+        {
+          "source": "src/lean_poc_deployment/local_cli.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py",
+          "sha256": "9c658c0409da3c6297ad349035bccb263a587cd6d9b07a9796ccbb7cdb6676f9"
+        },
+        {
+          "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/box_platform.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py",
@@ -334,7 +369,7 @@
         {
           "source": "src/lean_poc_deployment/entrypoint.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/entrypoint.py",
-          "sha256": "5161aec6d5a1fc684894a1011b3d577868cedaa7039ea647862a4628067fabd8"
+          "sha256": "8275c22ad1f9e3420630e773039902136ab036882f924b68f10ae5f602cae739"
         },
         {
           "source": "src/lean_poc_deployment/errors.py",
@@ -404,12 +439,12 @@
         {
           "source": "src/lean_poc_deployment/teardown.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/teardown.py",
-          "sha256": "edcf921aa92988176b756abf4bbc9b0b83ae1d855b6e8d487b67aaad7727cb55"
+          "sha256": "114b6e29725caaf105e67b5407de9a21c4ae9a9bfdc965bd4a0f1e91c316d011"
         },
         {
           "source": "src/lean_poc_deployment/teardown_cli.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/teardown_cli.py",
-          "sha256": "ec1271db5f57135189892e87f2df3ffc5fcb6e763ff1eb9604bc4e50788c3325"
+          "sha256": "93abb9350f1b06b0d53b38dff47030ecec982aed2455e9ddc4be12d70bfb6c3f"
         },
         {
           "source": "src/lean_poc_deployment/teardown_remote.py",

package/assets/generated/core/core/instructions/lean-docs.instructions.md

@@ -4,11 +4,42 @@ applyTo: "**/*.md"
 
 # Lean Documentation Rules
 
-Respect `.github/lean-workspace.json` and existing repository documentation.
+Respect `.github/lean-workspace.json`, `docs/lean-docs.json` when present, and existing repository documentation.
+
+## Authority
 
 - Do not create Product/Feature Briefs when the profile says they are unused.
 - Do not create duplicate requirement authorities.
+- `PROJECT_BRIEF.md` is a project briefing/navigation surface unless the repository explicitly says otherwise; do not let it silently compete with the accepted product/work-item authority.
 - Label experimental/supplemental briefs clearly.
 - Do not assume a Jira Epic is a Feature Brief.
 - Prefer one useful combined requirements artifact over a conveyor belt of docs when local requirements are appropriate.
-- Keep secret values out of tracked Markdown.
+
+## Ownership
+
+When `docs/lean-docs.json` is present, preserve its ownership boundary:
+
+- `project` — project-owned prose/decisions; update only when the current change actually owns that documentation.
+- `lean` — reusable Lean-managed material; update through the controlled reusable-package/baseline path rather than hand-diverging it in consumers.
+- `generated-evidence` — disposable projections reconstructed from current evidence; do not hand-edit or treat them as requirements.
+
+ADRs are project-owned decisions. Do not create or approve an architectural decision on the human's behalf merely because implementation evidence suggests one.
+
+## Generated views
+
+- Markdown is canonical; the local documentation website is a projection.
+- DB/System diagrams are current-by-default projections. Do not tell the developer to maintain, rebuild, or manually synchronize generated diagrams.
+- Keep disposable site/lab output under `.lean/` or another repository-approved ignored cache path by default.
+- A generated view may report `CURRENT`, `STALE`, `AVAILABLE / FRESHNESS UNKNOWN`, or `NOT GENERATED`; do not claim freshness without supporting evidence.
+- Repository/runtime/database evidence outranks stale generated views.
+
+## Change impact
+
+When a change materially affects public contracts, architecture, persistence, deployment/environments, developer workflow, testing strategy, or an architectural tradeoff, surface the likely documentation impact. Safe generated projections may be rebuilt automatically; human/project-authored prose should not be silently rewritten merely because code changed.
+
+Documentation follow-up is non-blocking unless the work item's acceptance criteria explicitly require documentation.
+
+## Safety
+
+- Keep sensitive values out of tracked Markdown, documentation manifests, and generated site data.
+- Preserve evidence labels and uncertainty rather than turning inference into authoritative architecture facts.

package/assets/generated/core/core/instructions/lean-workflow.instructions.md

@@ -34,4 +34,46 @@ After implementation review and local human acceptance, manually invoking `/deli
 
 Changed PR evidence re-opens the relevant review gate. Merge never implies production-deployment authorization.
 
+## Post-delivery documentation and learning handoff
+
+After engineering delivery is complete, documentation impact and learning are **non-blocking follow-ups**, not new delivery states or gates.
+
+Use the accepted work-item/PR diff conservatively to classify likely documentation impact. Examples:
+
+- public API/contract changes may affect architecture/runtime/API narrative;
+- services, dependencies, messaging, caches, auth, observability, deployment topology, or failure handling may affect System evidence;
+- entities, migrations, schema/DDL, ORM, queries, constraints, or indexes may affect DB evidence;
+- environment/deployment changes may affect operations docs;
+- durable developer/test workflow changes may affect engineering docs;
+- a consequential architectural tradeoff may deserve an ADR recommendation.
+
+A changed file proves relevant evidence was touched; it does not by itself prove a runtime or physical-schema change.
+
+When the relevant tools exist and prerequisites are safe, `/deliver` may best-effort prepare **disposable** evidence/site projections under:
+
+```text
+.lean/docs-cache/system/
+.lean/docs-cache/database/
+.lean/docs-site/
+```
+
+System evidence may be reconstructed from the current repository. Database evidence may be generated automatically only when a safe local development/test database path is already explicit; never guess a path merely to populate docs.
+
+If `tools/lean-docs/docs-site.py` exists, a build of the local documentation projection may follow safe lab preparation. Failure to build docs or a lab projection does not change `DELIVERY COMPLETE`.
+
+Do not silently rewrite project-owned narrative or approve/create an ADR solely because implementation evidence changed. Instead surface a compact `DOCUMENTATION IMPACT` handoff, for example:
+
+```text
+DOCUMENTATION IMPACT
+
+✓ Project brief: no material change detected
+★ System evidence: changed; current projection prepared
+★ Database evidence: changed; /db-lab recommended
+○ ADR consideration: new synchronous external dependency introduced
+
+/docs — explore the current project documentation
+```
+
+Use only claims supported by observed evidence. Keep `/docs`, `/db-lab`, `/system-lab`, `/code-walkthrough`, and `/learning-review` visible when useful, but never require them solely to complete engineering delivery.
+
 Do not pin or automatically escalate models.

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

@@ -2,7 +2,7 @@
 
 Deployment enablement is the guided operational lane between delivered deployment engineering and `/deploy`.
 
-A repository may have multiple named deployment environments, such as Staging and Production. Each environment owns its own confirmed machine/target binding, readiness evidence, data/backup state, credentials, and deployment policy.
+A **logical environment is not a physical computer**. A repository may define `demo`, `staging`, `production`, or other named environments; one developer may use only a workstation, several environments may share one VPS, or a desired deployment may remain explicitly deferred.
 
 The normal human-facing entry point is state-driven:
 
@@ -10,120 +10,157 @@ The normal human-facing entry point is state-driven:
 /deployment-readiness <environment>
 ```
 
-The workflow discovers current state and continues from the furthest safe point. The human does not need to choose separate `discovery`, `enable`, or `resume` modes.
-
-For a read-only local overview use:
+Read-only overview:
 
 ```text
 /deployment-readiness status [environment]
 ```
 
-Omit the environment from `status` to summarize all configured named environments without automatically probing every remote machine.
+The workflow discovers current topology/state and continues from the furthest safe point. The human does not choose separate `discovery`, `enable`, or `resume` modes.
+
+## Topology before machine questions
+
+Resolve these independently when repository evidence provides them:
 
-Older invocations that include a deployment-enabler ID and/or `discovery`, `enable`, or `resume` may be normalized for compatibility, but they are not the normal interface.
+```text
+environment name / role / purpose
+placement
+isolation
+exposure
+binding state
+adapter
+target/provider binding
+failure domain
+```
 
-## Human-facing readiness model
+Current placement classes include:
 
-The workflow should ask about simple environment-machine facts before exposing deployment-tool internals.
+- `workstation` — local execution; current reusable container adapter is loopback-only;
+- `remote-target` — an explicitly bound remote machine/target;
+- `managed-service` — only when a provider-specific adapter actually exists;
+- `deferred` — desired deployment exists but no current target/provider binding is selected.
 
-Human-facing facts normally include:
+Do not ask remote-machine questions until `remote-target` is actually the selected placement.
 
-- environment name/role;
-- hostname or IP address;
-- SSH/deployment user when applicable;
-- non-default SSH port when applicable;
-- target OS when known.
+## Workstation readiness
 
-Internal Deployment Kit concepts such as logical target name / `targetName`, SSH alias, profile path, identity path, known-hosts path, address override, and trust-record storage should be discovered, reused, or derived whenever possible. They are not normal first questions.
+A one-machine local/demo topology is normal.
 
-If existing configuration is present, show the known simple facts and ask the human to confirm them before remote checks. Do not make the human reconstruct already-recorded values.
+For current `workstation-container` support, readiness focuses on:
 
-If setup is partial, show what is known and ask only for the smallest missing fact or authorization.
+- local Docker/runtime availability;
+- repository-distributed local deployment tooling;
+- exact immutable artifact/image identity;
+- local port/container ownership and health configuration;
+- persistence prerequisites where relevant;
+- Production policy if the logical environment is Production.
 
-If setup is absent, start with the selected machine's hostname or IP address, then ask one additional simple fact at a time only when required.
+It does not require SSH, a hostname, target profile, host trust, Caddy, Avahi, or a second computer.
 
-## Discover, confirm, verify, continue
+The adapter's current exposure is loopback. Do not silently widen it to LAN/public sharing.
 
-Normal readiness cadence is:
+## Remote-target readiness
+
+For remote placement, retain the strict target/access model:
 
 ```text
-select environment
-→ inspect existing local/repository setup
-→ show simple known facts
-→ human confirms or corrects them
-→ authorize read-only connectivity/identity verification
-→ run repository/Deployment-Kit doctor/verify checks
-→ reuse working access OR repair only missing setup OR onboard a new workstation
-→ verify target/platform/security/artifact/registry/data prerequisites
-→ ENVIRONMENT READY TO DEPLOY
-→ /deploy <environment>
+named environment
+→ explicit target binding
+→ current address/discovery
+→ independently verified host identity
 ```
 
-The next readiness invocation re-discovers current state and resumes automatically. It does not require a new mode word after discovery or repair.
+Human-facing facts normally include hostname/IP, deployment user, non-default port, and target OS when relevant.
 
-Remote probing does not occur merely to build the initial local summary.
+Internal target/profile/SSH/trust paths should be discovered, reused, or derived whenever possible rather than pushed onto the human as first questions.
 
-Address discovery is not host trust. When SSH is used, unknown or changed host identity stops access; readiness must not recover by disabling host-key verification, silently enrolling new trust, scanning/selecting another host, weakening network controls, or redirecting to another environment.
+If existing configuration is present, show known facts for confirmation. If partial, ask only for the smallest missing fact. If absent, start with the actual machine/address rather than an internal target identifier.
 
-## Readiness writes versus deployment writes
+Remote probing requires explicit read-only authorization. Address discovery never substitutes for cryptographic host identity. Unknown/changed SSH identity fails closed.
 
-Readiness may perform bounded prerequisite/setup writes when separately authorized and supported by repository tooling, such as:
+## Deferred readiness
 
-- local environment binding;
-- key/agent/trust setup;
-- target-side access setup;
-- runtime/platform prerequisite setup;
-- data/backup directory preparation;
-- firewall preparation;
-- registry credential setup.
+A deferred placement is intentional configuration state:
 
-Readiness does **not** hide application deployment inside environment preparation.
+```text
+DEPLOYMENT INTENTIONALLY DEFERRED
+```
 
-Application container/process deployment, release-specific migration, application route registration, live application health/readiness, live smoke validation, and release-specific deployment/rollback evidence belong to `/deploy` when the repository's deployment contract includes them.
+It must not block repository generation, local development, CI, documentation, or learning. Readiness should explain the next material decision—choose/configure a supported target/provider adapter—without guessing infrastructure or asking for secrets.
 
-This distinction prevents a first-deploy deadlock: readiness proves that the environment can safely accept the selected artifact; `/deploy` creates and validates the live application state.
+## Managed-service boundary
 
-## Pre-deploy versus post-deploy evidence
+Managed hosting is adapter-specific. General model knowledge may recommend a provider, but absent a live catalog/implementation contract it remains `CATALOG GAP`/planned.
 
-Pre-deploy readiness may require:
+No provider credentials or provisioning should occur merely because a deployment outcome is public/shareable.
 
-- verified machine/target binding and host identity;
-- actual target OS/architecture and supported runtime/platform;
-- validated/available route names and collision checks;
-- approved immutable artifact identity;
-- registry/artifact access readiness;
-- persistence/data/backup prerequisites;
-- migration capability;
-- deployment locking capability;
-- rollback/recovery capability and boundaries;
-- stronger Production backup/recovery prerequisites when applicable.
+## Colocated environments
 
-Do not require first-deploy evidence that can only exist after the selected artifact is deployed, such as live route resolution, live application health, smoke success, deployed release identity, or execution-backed rollback evidence for that release.
+Two logical environments may intentionally share one physical failure domain.
 
-`/deploy` establishes those post-deploy facts and reports them from repository/tool evidence.
+Keep their targetable scope, runtime/container, route, data, readiness evidence, and authorization independent. When Staging and Production share one target, surface:
 
-## Existing and new workstations
+```text
+TOPOLOGY NOTE
 
-On an already-configured workstation, successful strict verification means onboarding/setup questions are skipped.
+Staging and Production are logically isolated but share one physical
+failure domain. This may fit POC cost/learning goals, but it does not
+demonstrate host-level Production isolation.
+```
 
-On a partially configured workstation, diagnose the exact missing state and repair only that state after the applicable bounded authorization.
+Production backup/recovery/security/deploy/destructive gates remain stronger regardless of colocation.
 
-On a fresh workstation, guide the minimum required profile/key/agent/trust/binding setup using the approved repository/Deployment-Kit commands. Reuse an already-valid developer-to-machine relationship across POCs when policy/tooling permits; do not create duplicate credentials simply because a new POC uses the same box.
+## Readiness cadence
+
+```text
+select environment
+→ resolve topology
+→ inspect placement-relevant local state
+→ show/confirm known facts
+→ authorize relevant read-only verification
+→ repair only missing prerequisites under explicit write gates
+→ ENVIRONMENT READY TO DEPLOY
+→ /deploy <environment>
+```
+
+For workstation placement there is no remote-access stage. For deferred placement the workflow intentionally stops before verification/provisioning.
+
+## Readiness writes versus deployment writes
+
+Readiness may perform bounded setup writes when separately authorized and supported by installed tooling, such as local configuration, SSH key/agent/trust setup, target-side access setup, runtime/platform preparation, data/backup directories, firewall preparation, or registry/provider credential configuration.
+
+Readiness does **not** hide application deployment inside setup.
+
+Application runtime deployment, release-specific migration, route/port publication, live health/readiness, smoke validation, and release-specific evidence belong to `/deploy` when the installed adapter defines them.
+
+## Pre-deploy versus post-deploy evidence
+
+Readiness proves only facts that can exist before deployment, such as:
+
+- logical environment/topology selection;
+- supported adapter availability;
+- local Docker readiness or verified remote target/identity depending on placement;
+- target OS/runtime when applicable;
+- artifact identity/access;
+- route/port ownership availability;
+- persistence/backup/migration prerequisites;
+- deployment lock/recovery capability;
+- stronger Production prerequisites.
+
+First-deploy live route, health, smoke, deployed-release identity, and release-specific rollback evidence are post-deploy facts owned by `/deploy`.
 
 ## Environment independence
 
-Readiness is environment-specific. Readiness of Staging does not prove Production is ready, and failure of one environment must never cause fallback to another environment or machine.
+Readiness of one logical environment never proves another environment ready—even if both share one physical target.
+
+Failure of one environment never redirects to another environment, machine, provider, or wider exposure.
 
-Production remains a role with stronger deployment, artifact, backup, recovery, and Human-in-the-Loop policy where required. It does not use a separate readiness command.
+Production remains a logical role/policy with stronger gates, not a separate readiness command or a requirement for a dedicated physical computer.
 
-Once the selected environment is ready to deploy, the repeatable deployment entry point is:
+Once ready:
 
 ```text
 /deploy <environment>
 ```
 
-`/deploy` verifies the selected environment/target/artifact evidence, presents the applicable write gate immediately before execution, delegates deterministic deployment mechanics, and then verifies repository-defined live route/readiness/smoke/deployment evidence.
-
-A Production deployment remains separately authorized and never becomes implicit because readiness passed. A non-production remote deployment still requires the repository/tool's bounded remote-write authorization.
-
-Remote read-only authorization never implies permission for writes. Secret values stay out of tracked documentation and logs. Database restore/destructive recovery remains a separate decision when data safety warrants it.
+`/deploy` verifies current topology/target/artifact evidence, presents the exact installed-tool authorization gate, delegates deterministic mechanics, and verifies placement-relevant live evidence.