@mriekki/project-forge 3.0.0 → 4.0.0

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: "Guide and execute setup for this workstation/workspace instance, including optional named deployment-environment onboarding and disposable deployment-path proof."
+description: "Guide and execute setup for this workstation/workspace instance, including verified local runtime convergence, optional remote-enabled capability, named deployment-environment onboarding, and disposable deployment-path proof."
 argument-hint: "[status|repair|local|remote|<environment>]"
 user-invocable: true
 disable-model-invocation: true
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 # Setup
 
-Purpose: give the developer one obvious entry point after cloning/opening a Project Forge workspace, whether this is the first workstation for the project or an additional independent workstation for an existing Project.
+Purpose: give the developer one obvious entry point after cloning/opening a Project Forge workspace and whenever this workstation later needs local or remote environment preparation.
 
 Normal first use is simply:
 
@@ -16,7 +16,26 @@ Normal first use is simply:
 /setup
 ```
 
-The skill is the conversational/orchestration layer. Repository-local setup scripts and Deployment Kit commands remain the deterministic machine implementations. Do not duplicate installer, SSH, Docker, deployment, or profile mechanics in the skill when the repository already provides them.
+Supported focused forms include:
+
+```text
+/setup status
+/setup repair
+/setup local
+/setup remote
+/setup <environment>
+```
+
+`/setup` is the conversational/orchestration layer. Repository-local setup scripts and Deployment Kit commands remain the deterministic machine implementations. Do not duplicate installer, SSH, Docker, deployment, or profile mechanics in the skill when the repository already provides them.
+
+The governing readiness invariant is:
+
+```text
+REQUESTED MODE != ready state
+READY = verified operational evidence
+```
+
+A requested local/remote capability becomes ready only after its applicable readiness contract passes. Preserve the prior ready state when convergence fails.
 
 ## 1. Resolve this workspace instance
 
@@ -29,12 +48,12 @@ From the repository root inspect only what is needed:
 - `.github/project-forge-workspace.json` and Project Forge/component baselines when present;
 - `scripts/setup.ps1` on Windows or `scripts/setup.sh` on macOS;
 - current Git branch/status/upstream evidence so setup does not overwrite unrelated work;
-- workstation-local developer-environment evidence when present;
-- the actual workstation OS/platform and machine-local identity needed to describe this workspace instance.
+- workstation-local setup/readiness evidence when present;
+- actual workstation OS/platform and machine-local identity needed to describe this workspace instance.
 
 If package-managed Project Forge files are drifted, route that problem to `/project-forge-update`; do not silently replace managed files during setup.
 
-A **workspace instance** is one checkout of one Project Forge project on one developer workstation. Multiple workspace instances for the same project are normal and may be active at the same time.
+A **workspace instance** is one checkout of one Project Forge project on one developer workstation. Multiple workstations may work on the same project concurrently, and multiple workspace instances are normal.
 
 When project provenance/configuration exists but this computer has no local readiness evidence for the checkout, treat the situation as:
 
@@ -44,23 +63,33 @@ EXISTING PROJECT — NEW WORKSTATION
 
 Do not require another workstation to be online and do not treat another computer as the project's primary machine.
 
-Detect the current OS automatically. Do not ask the developer which setup launcher to use when the platform can be observed. Prefer a compact preflight such as:
+Detect the current OS automatically. Do not ask the developer which setup launcher to use when the platform can be observed.
+
+A workspace instance owns machine-local state such as local runtime/data, SSH private keys/trust, credential-manager entries, Docker state, and repository-scoped readiness evidence. Git/GitHub is the shared source-code coordination boundary. Never invent a central workstation registry merely to coordinate another computer.
+
+## 2. `status` is read-only
+
+`/setup status` performs no setup writes. Inspect current workstation evidence and live prerequisites, then report local workspace/runtime readiness plus any configured remote capabilities.
+
+Prefer a compact result such as:
 
 ```text
-EXISTING PROJECT — NEW WORKSTATION
+SETUP STATUS
 
-Project ............ <project>
-Platform ........... Windows / macOS
-Setup launcher ..... <detected launcher>
-Personal profile ... FOUND / NOT CONFIGURED / DEFERRED
-Local setup ........ READY / NOT CONFIGURED / BLOCKED
-```
+Workspace ......... READY / NOT CONFIGURED / BLOCKED
+Local runtime ..... READY / STALE / NOT APPLICABLE
+Build/tests ....... READY / STALE / BLOCKED
+Local data ........ READY / NOT APPLICABLE / BLOCKED
+Personal profile .. READY / DEFERRED / BLOCKED
+Remote capability . READY / PARTIAL / NOT CONFIGURED
 
-A workspace instance owns machine-local state such as local runtime/data, SSH private keys/trust, credential-manager entries, Docker state, and repository-scoped developer-mode evidence. Those values are not synchronized from another workstation.
+NEXT
+/setup local | /setup remote | /setup <environment> | /next-step
+```
 
-Git/GitHub is the shared source-code coordination boundary. The personal Project Forge profile is the shared portable non-secret target-definition boundary. Do not invent a central device registry merely to support another workstation.
+Do not silently repair state during `status`.
 
-## 2. Run the generated local setup for the observed OS
+## 3. Run generated workstation setup
 
 Select the launcher for the actual workstation OS:
 
@@ -69,25 +98,23 @@ Windows  -> .\scripts\setup.ps1
 macOS    -> ./scripts/setup.sh
 ```
 
-Do not ask the developer to choose an OS launcher when the OS can be observed.
-
 For normal setup, run the launcher with repository restore enabled when supported:
 
 ```text
 setup --restore
 ```
 
-For `status`, use the script's read-only check mode when supported:
+For a read-only generated setup check, use the script's check mode when supported:
 
 ```text
 setup --check
 ```
 
-A manually invoked `/setup` authorizes routine, bounded, non-destructive local setup that the generated script already owns: supported tool installation, VS Code extension installation, dependency restore, personal Project Forge profile initialization, and other declared workstation preparation. Do not add another confirmation merely to start those routine actions.
+A manually invoked `/setup` authorizes routine, bounded, non-destructive local setup that the generated script already owns: supported tool installation, VS Code extension installation, dependency restore, personal Project Forge profile initialization, and other declared workstation preparation.
 
 Stop before destructive replacement, unrelated machine mutation, secret disclosure, or repair outside the declared setup contract.
 
-## 3. Reach local workspace readiness first
+## 4. `/setup local` converges verified local development readiness
 
 The first success target is:
 
@@ -95,88 +122,87 @@ The first success target is:
 LOCAL WORKSPACE READY
 ```
 
-Remote environments must not block initial local setup unless the approved project explicitly requires a remote dependency for local development.
+Remote environments must not block local setup unless the approved project explicitly requires a remote dependency for local development.
 
-After the generated setup script passes:
+If application scaffolding is intentionally deferred by `SCAFFOLD_PLAN.json` or approved work-item state, local workspace readiness may be valid without an application runtime. Do not invent source/runtime work merely to make local setup look complete.
 
-- if application source/runtime already exists, use `/developer-env-mode local` to converge and verify local persistence/build/tests/container/health as applicable;
-- if `SCAFFOLD_PLAN.json` or the approved work-item plan intentionally defers application scaffolding, report local **workspace** readiness without inventing application runtime work;
-- if Docker or another runtime is not required by the current project state, mark it `NOT APPLICABLE`, not failed.
+When application source/runtime exists, converge only the repository-owned local development contract.
 
-Each workstation normally owns independent local development data. Reproduce schema/migrations/seed behavior as the project defines it; do not silently copy mutable local databases or runtime state from another computer.
+### A. Prerequisites and restore
 
-## 4. Establish/sync the developer's personal Project Forge profile
+Verify supported tools/versions using repository setup/doctor tooling when present. Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions.
 
-When the installed Deployment Kit exposes personal-profile operations, `/setup` should establish the authenticated developer's portable non-secret profile as routine setup state. This repo is per developer, not per Project or workstation.
+### B. Local persistence
 
-First inspect profile status and authenticated GitHub login. If the expected private repository is missing, tell the developer what will happen before writing:
+For SQLite local development, resolve the project-owned database path and migration/initialization contract from repository evidence. Prefer installed Deployment Kit local SQLite ensure/status primitives when available.
 
-```text
-Project Forge will create a private GitHub repository for your portable environment definitions:
+When the database is absent, creating the owned local SQLite file/directory and running normal forward initialization/migrations may be routine setup.
 
-  <login>/project-forge-profile
+If an existing database is corrupt, incompatible, has unexpected ownership/schema state, or recovery would be destructive, stop. **Never delete, replace, reset, or migrate destructively** merely to make setup pass. Other persistence engines require their own explicit repository-owned setup contract.
 
-It stores only non-secret target definitions and preferences. SSH private keys,
-passwords, PATs, known-host contents, and machine-local state stay on this computer.
-```
+Each workstation normally owns independent local development data; do not silently copy mutable local databases or runtime state from another computer.
+
+### C. Build and tests
 
-Then invoke the repository-provided deterministic operation within the already-authorized `/setup` action:
+Run the repository's required local build and test commands. A missing/stale build is a normal convergence condition; rebuild it. If required build/tests fail, report:
 
 ```text
-python tools/project-forge-deployment/project-forge-deploy.py environment profile ensure --yes
+LOCAL MODE NOT READY
 ```
 
-If the repo already exists and is verified private, reuse it. On an additional workstation, sync/apply the validated portable profile using the repository-provided profile operation when supported, while preserving valid non-conflicting machine-local definitions.
+and do not record local runtime readiness.
 
-Never import another workstation's private key, known-host contents, PAT, password, local database, Docker credential state, or readiness claim.
+### D. Local immutable runtime artifact
 
-If automatic profile creation cannot proceed, use the explicit Bootstrap-like fallback: ask the developer to create the exact private `<login>/project-forge-profile`, reply `created`, then re-verify owner/name/privacy before deterministic initialization. Never ask the developer to paste credentials into chat.
+When local execution is Docker-based, build/acquire the application image through repository-owned commands and resolve an immutable identity. A repository-supported workstation adapter may accept an exact registry digest or a local Docker image ID (`sha256:<64 hex>`) for workstation-only execution. Never treat a mutable tag as final runtime identity.
 
-If GitHub is temporarily unavailable, otherwise-ready local development remains valid. Report profile portability as `DEFERRED`.
+### E. Local runtime and health
 
-## 5. Present a guided environment setup selection
+Converge the project-owned local application runtime through the repository-distributed workstation adapter when available. Current reusable workstation-container topology remains loopback-only:
 
-After local readiness/profile state is understood, show the environments that this workstation can be prepared to use.
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+```
 
-This is an intentionally **multi-select** decision because preparing the workstation for several environments in one setup session is valid. When the host exposes structured choice UI, use its native multi-select control; in VS Code use the question surface such as `vscode_askQuestions`. Do not emulate checkboxes as ordinary chat text when native multi-select is available.
+Mount only project-owned local persistence as required. Verify the declared health endpoint/smoke check when the project defines one. Do not resolve SSH targets, publish images, create public routes, or deploy Staging/Production while preparing local development.
 
-Conceptual choices are:
+Only after applicable prerequisites, persistence, build/tests, runtime, and health checks pass should local readiness be recorded as ready.
 
-- `Local development`
-- each existing project-defined environment from current topology
-- `Other / define another environment`
+## 5. Establish/sync the personal Project Forge profile
 
-Recommend/select `Local development` by default only because Project Forge's local-first setup policy makes it the normal initial capability and remote environments must not block local coding. Surface that rationale briefly. Do not automatically mark any additional environment recommended without project-specific evidence.
+When installed Deployment Kit exposes personal-profile operations, `/setup` should establish the authenticated developer's portable non-secret profile as routine setup state. This repo is per developer, not per Project or workstation.
 
-If the host has no structured multi-select UI, a checkbox-like or concise textual list is the documented fallback. Free-form selection remains valid.
+If the expected private profile repository is missing, explain the intended creation before writing. It stores only non-secret target definitions/preferences. SSH private keys, passwords, PATs, known-host contents, mutable local databases, Docker credentials, and machine-local readiness remain local.
 
-Rules:
+Use repository-provided deterministic profile operations when supported. If GitHub is unavailable, otherwise-ready local development remains valid; report profile portability as `DEFERRED`.
 
-- Existing named environments come from the project's current deployment topology, not a hard-coded Staging/Production list.
-- Show each environment's purpose/role compactly when the name alone is ambiguous.
-- Selecting an environment means **prepare this workstation for that environment**; it does not deploy the project's real application.
-- Do not force the developer to configure every environment in one session. `/setup` can be rerun later to add another capability.
-- The recorded setup scope comes from the developer's actual selections, not from any recommended/default choice.
+Never ask the developer to paste credentials into chat.
 
-### Topology source of truth
+## 6. Present guided environment setup selection
 
-Prefer project-owned mutable deployment topology:
+After local readiness/profile state is understood, show the environments this workstation can be prepared to use.
 
-```text
-DEPLOYMENT_TOPOLOGY.json
-```
+This is an intentionally **multi-select** decision because preparing the workstation for several environments in one setup session is valid. When the host exposes structured choice UI, use native multi-select; in VS Code use a question surface such as `vscode_askQuestions`.
 
-Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
-
-`PROJECT_BOOTSTRAP.json` is generation/provenance evidence and should not be casually rewritten merely because a developer adds an environment later.
+Conceptual choices are:
+- `Local development`;
+- each existing project-defined environment from current topology;
+- `Other / define another environment`.
 
-If an older Project has no `DEPLOYMENT_TOPOLOGY.json` and the developer chooses to add/change a logical environment, first materialize the currently approved deployment topology into the project-owned file, then make the scoped project configuration change there. Preserve the original Bootstrap provenance file.
+Recommend/select `Local development` by default only because Project Forge is local-first. Do not automatically recommend additional environments without project-specific evidence.
 
-A topology entry should keep logical identity distinct from purpose and placement. A name such as `demo`, `qa`, or `prod-east` is the command-facing environment identity. Its purpose remains one of the project-supported semantic roles such as development/demo/staging/production.
+Rules:
+- existing names come from `DEPLOYMENT_TOPOLOGY.json`, falling back to Bootstrap topology only for the initial topology;
+- selecting an environment means **prepare this workstation for that environment**, not deploy the project application;
+- do not force every environment to be configured in one session;
+- the recorded setup scope comes from the developer's actual selections;
+- later environment changes belong in mutable project topology, not casual rewrites of Bootstrap provenance.
 
-### Other / define another environment
+### Define another environment
 
-When the developer chooses **Other**, guide only the material choices needed to create a durable environment definition, normally:
+For `Other / define another environment`, collect only material durable facts, normally:
 
 ```text
 Name ............ demo
@@ -187,11 +213,12 @@ Isolation ....... <project/catalog-supported option>
 Exposure ........ <project/catalog-supported option>
 ```
 
-Use host-native single-select controls for bounded mutually exclusive fields such as purpose/placement/isolation/exposure when available. Keep names, targets, and other factual values open-ended. Recommend at most one option only when current topology/catalog evidence or a clear engineering tradeoff supports it; otherwise show the bounded choices without a recommendation. Always allow `Other / specify` or `Not sure — recommend one` where appropriate.
+Use structured single-select controls for bounded mutually exclusive fields when available. Keep names/targets open-ended. Persist the approved logical environment definition before claiming it is configured.
 
-Persist the approved logical environment definition before claiming it is configured. Normalize the command-facing name to the repository-supported safe slug form. Once saved, all normal environment commands use that exact name, for example:
+Normal commands then use that exact name, for example:
 
 ```text
+/setup demo
 /deployment-readiness demo
 /deploy demo
 /tear-down demo
@@ -199,54 +226,43 @@ Persist the approved logical environment definition before claiming it is config
 
 Do not create an environment whose required placement/adapter is unsupported; report the concrete `CATALOG GAP` or deferred state instead.
 
-## 6. Prepare selected remote environments
+## 7. `/setup remote` and `/setup <environment>` prepare remote-enabled capability
 
-For each selected non-local environment, reuse the project's topology plus the developer's portable target/profile definition and establish this workstation's machine-specific capability as far as supported:
+Remote setup proves that this workstation can later work with the configured non-Production or Production-class environment under its normal safety contract. It does **not** publish an artifact or deploy the real application.
 
-```text
-logical environment
-→ target/profile definition
-→ this-workstation SSH identity/trust when applicable
-→ target access
-→ host/platform prerequisites/readiness
-→ deployment-path proof when supported
-```
+Verify as applicable:
+- local developer prerequisites still needed to build/test;
+- project topology contains the selected non-deferred environment;
+- exact target/provider binding exists when required;
+- workstation-to-target identity/trust/access is valid;
+- target OS/runtime/platform prerequisites are valid;
+- persistence/readiness prerequisites can be inspected safely;
+- GitHub/registry access needed for a later release/publish step is available;
+- repository deployment tooling/baselines are coherent.
 
-Never copy SSH private keys/trust from another workstation. Another workstation's successful readiness is useful project context, not proof that this workstation can deploy.
+For remote SSH preserve strict host identity. Unknown/changed host identity is a stop condition. Never copy SSH private keys/trust from another workstation and never fall back to another target/provider simply to make setup pass.
 
-If host prerequisites cannot yet be prepared automatically, report the exact preparation gap instead of weakening `sudo`, trust, or credential boundaries.
+Remote readiness does not require configuring Production when the selected environment is non-Production. Production classification remains project topology/policy, not a literal-name check.
 
-## 7. Prove the deployment path with a disposable Project Forge probe
+## 8. Prove supported remote mechanics with a disposable Project Forge probe
 
 When the installed Deployment Kit exposes environment proof operations, a selected remote environment should normally be taken through an end-to-end **environment proof deployment** during setup.
 
-The proof is not the Project application. It is a tiny disposable Project Forge-owned probe that should:
+The proof is not the Project application. It is a tiny disposable Project Forge-owned probe:
 
 ```text
-acquire a small stable probe image on this workstation
-→ resolve its exact immutable digest
-→ transfer that exact image using the real workstation-mediated path
-→ deploy under a reserved probe identity
+acquire a stable probe image locally
+→ resolve exact immutable digest
+→ transfer using the real workstation-mediated path
+→ deploy under reserved probe identity
 → verify runtime/HTTP health
-→ remove the probe
+→ remove probe
 → verify cleanup
 ```
 
-For the current standard Deployment Kit, use the repository-distributed command when available, conceptually:
-
-```text
-python tools/project-forge-deployment/project-forge-deploy.py environment proof plan \
-  <target> --owner-repo <owner/repo> --environment <name>
-
-python tools/project-forge-deployment/project-forge-deploy.py environment proof run \
-  <target> --owner-repo <owner/repo> --environment <name> --yes
-```
-
-Use the actual installed command/help contract rather than blindly copying examples.
-
-A successful proof demonstrates this workstation can use the real image-transfer/application-runtime/health path. It must not create project data or claim the project's application has been deployed.
+Use the actual installed command/help contract. Never claim the Project application is deployed because the probe succeeds.
 
-Preferred state after proof:
+Preferred evidence:
 
 ```text
 Environment ........... demo
@@ -256,110 +272,44 @@ Deployment path ....... PROVEN
 Project application ... NOT YET DEPLOYED
 ```
 
-If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim a clean setup.
-
-### Authorization during setup
-
-For a selected **non-Production** environment, the developer's explicit `/setup` selection plus a clear preview of the disposable proof may cover the bounded proof write. Use the deterministic tool's exact authorization contract and do not add multiple ceremonial prompts.
-
-For any environment whose resolved purpose is **production**, keep one explicit consequential gate before the proof writes to it. Render this gate through host-native **single-select** structured choice UI when available:
-
-```text
-PRODUCTION ENVIRONMENT PROOF
-
-Project Forge is ready to temporarily deploy a disposable environment probe to <name>,
-verify it, and remove it. No project application or project data will be deployed.
-```
-
-Choices:
-
-- `Run Production environment proof`
-- `Verify access/readiness only`
-- `Skip this environment for now`
-
-Do not mark a choice recommended merely because a recommendation field exists. Recommend `Run Production environment proof` only when the selected setup goal and current evidence make end-to-end proof the clearly preferred next step, and explain why. Use a numbered text fallback only when structured choice UI is unavailable.
-
-A custom Production name such as `prod-east` remains Production because of its resolved purpose/classification. Never downgrade Production safety based on the literal environment string.
-
-## 8. First real application deployment remains streamlined
-
-Environment proof should intentionally answer environment/mechanics questions once. Later, the first `/deploy <environment>` with real application code should ask only application-specific questions that are still unresolved, such as exact health contract, persistence, exposure/route, or immutable application artifact policy.
-
-Do not repeat already-proven target/access/transport setup unless evidence changed.
-
-Environment proof never authorizes a later real application deployment, and Production proof never authorizes Production application deployment.
-
-## 9. Human workspace acceptance remains meaningful
-
-Machine success is evidence, not human acceptance.
-
-When selected setup work passes, report what is ready and hand off to `/next-step` for remaining human editor/workspace acceptance and work-item navigation.
-
-Preferred completion shape:
-
-```text
-SETUP COMPLETE
-
-Workspace instance .... <machine/platform or local friendly name>
-Workstation tools ...... READY
-Personal profile ....... READY / DEFERRED
-Project dependencies ... READY / DEFERRED
-Local runtime .......... READY / DEFERRED / NOT APPLICABLE
-Workspace checks ....... READY
-
-ENVIRONMENT CAPABILITIES
-Local .................. READY
-Demo ................... PROVEN / READY / NOT CONFIGURED
-Staging ................ PROVEN / READY / NOT CONFIGURED
-Production ............. PROVEN / ACCESS READY / NOT CONFIGURED
-
-Next:
-  /next-step
-```
-
-Do not silently mark editor/agent discovery accepted on the developer's behalf.
-
-## 10. Concurrent workspace rules
-
-Multiple workstations may work on the same project concurrently.
-
-Prefer independent short-lived branches for independent workstreams. If this checkout uses a branch another workspace may also update, inspect upstream/remote divergence before branch-changing, delivery, or history-sensitive actions. A remote branch advancing from another workstation is normal evidence, not corruption.
+For a Production-class environment, keep the proof explicitly labeled as a **PRODUCTION ENVIRONMENT PROOF** only when topology says the selected environment is Production-class. The disposable proof still does not authorize real Production deployment.
 
-Stop before force/reset/rebase or silent loss of local work; route reconciliation through the normal Git/work-item flow.
-
-`/setup` itself does not commit, push, merge, switch work-item branches, copy worktree changes between computers, or use stash as cross-workstation storage.
-
-Shared remote environment mutations remain protected by the Deployment Kit's environment/application locking and readiness contracts.
-
-## 11. `status`, `repair`, local, remote, and named-environment options
+If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim a clean setup.
 
-`/setup status` is read-only. Report current setup/readiness for **this workspace instance** and all project-defined environments without mutating them.
+## 9. `repair` is bounded and fail-closed
 
-`/setup repair` repairs only missing/safely reproducible state. Preserve valid tools, keys, trust, databases, Docker state, and project files.
+`/setup repair` may re-run safe deterministic setup/readiness operations after classifying the blocker. It may create missing local directories/caches, restore dependencies, rebuild outputs, create a new owned local database, run normal forward initialization, or recreate an owned disposable/local runtime when the repository contract permits those actions.
 
-`/setup local` targets local workstation convergence.
+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;
+- changing public/LAN exposure;
+- deploying Staging or Production.
 
-`/setup remote` presents the guided named-environment selector rather than assuming only Staging/Production.
+## 10. Relationship to deployment readiness
 
-`/setup <environment>` may directly select one existing project-defined environment (for example `/setup demo`) and run the same readiness/proof flow. It must resolve the name from project topology and never invent or silently fall back to another environment.
+`/setup` establishes workstation/workspace capability and may prove reusable environment mechanics.
 
-When the installed Deployment Kit exposes profile migration and this workstation already has valid target definitions but no personal profile model, prefer the deterministic migration command. Migration may publish only sanitized target definitions and preserve existing keys/trust; it must not deploy applications or delete old credentials automatically.
+`/deployment-readiness <environment>` remains the later pre-deployment check for one exact environment. It reuses fresh setup-time proof where valid, then verifies application-specific prerequisites for the real deployment.
 
-## 12. Credential boundary
+`/setup` never implies `/deploy`. A successful setup/proof does not authorize a remote or Production application write.
 
-Never ask the developer to paste passwords, PATs, private SSH keys, or other credentials into chat.
+## 11. Completion and handoff
 
-When a repository/tool needs a credential, direct the deterministic local tool to prompt in the local terminal using a hidden/secure prompt. Secrets remain workstation-local and must not be committed to the Project repository or portable profile.
+After setup, report evidence rather than inferring human acceptance.
 
-## 13. Relationship to other Project Forge commands
+A generated setup/doctor/proof success is machine evidence. Human workspace acceptance remains distinct.
 
-- `/setup` — prepare this workstation/workspace instance and selected named environment capabilities.
-- `/progress` — read-only lifecycle/workspace/environment status.
-- `/next-step` — one sensible next action after current evidence is known.
-- `/developer-env-mode` — direct/advanced local-vs-remote operational readiness command.
-- `/start-work <ID>` — implementation authorization after workspace acceptance.
-- `/deployment-readiness <environment>` — readiness for any exact project-defined environment.
-- `/deploy <environment>` — deploy the real application to any exact project-defined environment, with Production classification preserved.
-- `/tear-down <environment>` — destructively clean only the exact named environment after its own authorization gates.
+Useful next actions include:
+- `/next-step` — one sensible next action after current evidence is known;
+- `/start-work <ID>` — implementation authorization after workspace acceptance;
+- `/deployment-readiness <environment>` — final pre-deploy evidence for a prepared environment;
+- `/deploy <environment>` — only after readiness and its own authorization contract;
+- `/tear-down <scope>` — destructive cleanup under its separate gate.
 
-Keep setup focused: one front door, automatic OS detection, project-defined environment names, deterministic tooling underneath, disposable proof where supported, and stronger Production gates only where they materially matter.
+Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -41,7 +41,7 @@ If local requirements exist, are they DRAFT or APPROVED?
 Are material decisions unresolved?
 ```
 
-If detailed precision is warranted but incomplete, recommend `/refine-requirements`, `/grill-me`, or `/grill-with-docs` rather than silently inventing behavior.
+If detailed precision is warranted but incomplete, recommend `/refine-requirements` or `/grill-me` rather than silently inventing behavior. `/grill-me` may remain read-only or, when the human selects its session-level reconciliation option, write resolved decisions into permitted authorities.
 
 If local requirements are DRAFT and carry material behavior, human approval is the gate before substantive planning/implementation.
 
@@ -114,11 +114,10 @@ Explain why the level was chosen.
 For STANDARD/ELEVATED work, once requirements are ready, coaching may be offered but is never required. When the human needs to choose, render a **single-select structured choice** through the host UI when available; in VS Code use the native question surface such as `vscode_askQuestions`.
 
 Relevant choices are:
-
-- `Continue without coaching` — `RECOMMENDED` default
-- `/coach` for a short pre-build concept review
-- `/grill-me` for challenge rather than teaching
-- `Stop`
+- `Continue without coaching` — `RECOMMENDED` default;
+- `/coach` for a short pre-build concept review;
+- `/grill-me` for challenge rather than teaching;
+- `Stop`.
 
 Use a numbered text list only when structured choice UI is unavailable. For LIGHT work, do not interrupt with coaching unless requested.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {

package/assets/generated/core/core/agents/coach.agent.md

@@ -1,69 +0,0 @@
----
-name: Coach
-description: Optional guided engineering-learning agent using actual repository context for concepts, code walkthroughs, debugging, coding/SQL/system-design drills, interviews, diagrams, and resources.
-user-invocable: true
-disable-model-invocation: true
----
-
-# Coach
-
-You are the optional engineering-learning perspective.
-
-Coaching is never required to start, continue, review, accept, deliver, merge, or complete engineering work.
-
-## Core behavior
-
-- Do not edit production code or implement fixes for the developer.
-- Do not invoke subagents.
-- Do not silently broaden product scope.
-- Do not pin/request/switch to a premium model automatically.
-- Read minimum relevant context.
-- Use actual repository code, requirements, tests, diffs, incidents, and decisions when useful.
-- Ask one material question at a time.
-- Continue automatically until stop/natural completion.
-- Adapt difficulty to demonstrated understanding.
-- Challenge shallow explanations.
-- Distinguish actual implementation/understanding from AI-generated work or study.
-
-## Depth and levels
-
-Depth: Light, Focused, Deep, Broad, or Coach recommends.
-
-Levels:
-
-```text
-L1 Recognize
-L2 Explain
-L3 Trace
-L4 Apply / Debug
-L5 Defend / Design
-L6 Interview Ready
-```
-
-Do not inflate mastery.
-
-## Modes
-
-Support concept learning, real-code walkthroughs, debugging, coding/DSA, SQL/database, design defense, system design, interview drills, gap assessment, learning paths, diagrams, and optional external resources.
-
-For a structured walkthrough of a changed implementation across a Git/PR/commit change set, route to `/code-walkthrough` when available. Use Coach directly for ad-hoc code explanation or deeper concept exploration.
-
-Use installed learning assets when present; otherwise coach directly from the repository/context.
-
-## Adaptive questioning
-
-Weak answer → teach/simplify/own-words explanation.
-
-Solid answer → application/edge case.
-
-Strong answer → tradeoff/debug/design.
-
-Very strong answer → scale/change assumptions/interviewer pressure.
-
-## Resources and progress
-
-Prefer official documentation and a small number of current high-quality tutorials/resources. External material is optional.
-
-Only update an optional learning-progress tracker with explicit human choice.
-
-Never turn study or personal-project understanding into false claims of professional experience.