@mriekki/project-forge 2.1.0 → 3.0.0

package/assets/generated/core/core/skills/code-walkthrough/SKILL.md

@@ -58,6 +58,8 @@ Deep    — important methods/blocks, state/data flow, dependencies, edge cases,
 
 Depth may vary by file. Treat trivial configuration lightly unless it materially affects behavior; spend more depth on implementation anchors.
 
+If the human needs to choose a depth, use host-native **single-select structured choice UI** when available. Do not recommend a depth unless the requested learning goal or change complexity clearly supports one; `Focused` is a descriptive default, not permission to manufacture a recommendation.
+
 ## 4. Build the walkthrough plan
 
 Before explaining the first file:
@@ -125,13 +127,15 @@ Group trivial generated/configuration changes when that improves learning, but d
 
 Default to one file or one tightly related file group at a time. Do not dump the whole implementation at once.
 
-At a natural file boundary, show a compact navigation cue such as:
+At a natural file boundary, a compact navigation cue may be shown:
 
 ```text
 NEXT: <suggested file>
 Use: next | deeper | explain this | trace | why this design | diagram | quiz | debug | interview | skip | stop
 ```
 
+When the host exposes structured choice UI and the human is being asked to choose among these navigation actions, prefer a relevant **single-select** subset rather than forcing the human to type a token. Keep free-text commands valid. Do not turn the full command vocabulary into a large mandatory selector when the next action is already obvious.
+
 Interpret these naturally:
 - `next` — continue to the suggested next file;
 - `deeper` — increase depth for the current file/topic;
@@ -185,13 +189,13 @@ When the planned change set is covered or the human stops, summarize:
 - learning gaps or topics worth revisiting,
 - optional next learning actions.
 
-Offer only relevant next choices, such as:
+When offering bounded next actions, use host-native **single-select structured choice UI** when available. Relevant choices may include:
 
-```text
-1. /learning-review <same scope> [READ ONLY]
-2. /coach <specific concept> [READ ONLY]
-3. Return to engineering workflow [NO ACTION]
-4. Stop [NO ACTION]
-```
+- `/learning-review <same scope>` `[READ ONLY]`
+- `/coach <specific concept>` `[READ ONLY]`
+- `Return to engineering workflow` `[NO ACTION]`
+- `Stop` `[NO ACTION]`
+
+Recommend at most one only when the walkthrough evidence shows a clear learning gap or the engineering workflow is clearly the better next step; otherwise present the choices without a recommendation. Use a numbered text menu only when structured choice UI is unavailable.
 
 Do not create a new engineering state such as `CODE_WALKTHROUGH_PENDING`. Walkthrough completion is learning evidence, not a delivery gate.

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -94,7 +94,9 @@ If the checkout is dirty, ahead, diverged, intentionally pinned, or ambiguous, p
 
 ## 5. Present one bounded component-sync choice
 
-For a safe local source:
+Use the host-native **single-select structured choice UI** when available because exactly one next action is authorized. In VS Code use the native question surface such as `vscode_askQuestions`. Preserve the consequence labels and show the recommended choice. Use a numbered text list only when structured choice UI is unavailable.
+
+For a safe local source, show the evidence:
 
 ```text
 CORE SYNC READY
@@ -102,13 +104,15 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: LOCAL <core-path>
 Distribution: <distribution>
-
-1. Sync the component-only Core baseline [GIT + FILE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
-For a configured remote source:
+Then offer:
+
+- `Sync the component-only Core baseline` `[GIT + FILE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
+For a configured remote source, show:
 
 ```text
 CORE SYNC READY
@@ -116,17 +120,19 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: REMOTE PROVIDER
 Provider: <provider repository>
-
-1. Request remote Core sync [REMOTE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
+Then offer:
+
+- `Request remote Core sync` `[REMOTE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
 The selected choice does not authorize merge, release publication, or deployment.
 
 ## 6. Local component path
 
-After local option 1 is selected:
+After `Sync the component-only Core baseline` is selected:
 
 1. Refresh Core remote state.
 2. Reclassify the accepted/default Core branch.

package/assets/generated/core/core/skills/define-feature/SKILL.md

@@ -63,7 +63,7 @@ Do not create a competing source of truth.
 
 Ask one material question at a time when a real decision is unresolved.
 
-For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
+For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. When the host exposes structured choice controls, render mutually exclusive alternatives through single-select UI rather than a plain numbered menu; use multi-select only when several simultaneous selections are actually valid. Keep `Other / specify` or free-text available when choices may be incomplete. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
 
 Clarify only what matters, such as:
 - user/engineering outcome,
@@ -123,22 +123,13 @@ If systematic lower-level coverage is valuable, recommend:
 
 ## 7. Guided ending
 
-Use a small evidence-backed menu, for example:
+Use a small evidence-backed set of relevant actions. In VS Code, render them through the host-native **single-select structured choice UI** such as `vscode_askQuestions` when available. Conceptual choices may include:
 
-```text
-CURRENT STATE
-<what is defined and what remains open>
-
-RECOMMENDED NEXT STEP
-<one action and why>
-
-OPTIONS
-1. Review definition [READ ONLY]
-2. Grill unresolved behavior [READ ONLY]
-3. Refine detailed requirements [READ ONLY initially]
-4. Approve requirements/scope when applicable [REQUIREMENTS GATE]
-5. Start work if already ready [READ ONLY]
-6. Stop [NO ACTION]
-```
+- `Review definition` `[READ ONLY]`
+- `Grill unresolved behavior` `[READ ONLY]`
+- `Refine detailed requirements` `[READ ONLY initially]`
+- `Approve requirements/scope` `[REQUIREMENTS GATE]` when applicable
+- `Start work` `[READ ONLY]` when already ready
+- `Stop` `[NO ACTION]`
 
-Only show relevant options. A file-changing choice authorizes only that bounded action/session.
+Make the recommended next action visible when evidence supports one. Use a numbered text menu only when structured choice UI is unavailable. A file-changing choice authorizes only that bounded action/session.

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

@@ -197,7 +197,7 @@ If a Draft PR was required earlier and all readiness conditions are now satisfie
 
 ## 8. Single merge + finalize gate
 
-When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate:
+When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate. First show:
 
 ```text
 MERGE READY
@@ -206,13 +206,17 @@ PR CI: GREEN
 Reviewer: READY
 PR diff: matches accepted delivery scope
 Mergeable/policy: <observed state>
-
-1. Merge and finalize delivery [HUMAN ACCEPTANCE + GITHUB/GIT WRITE] — recommended
-2. Review final PR diff first [READ ONLY]
-3. Leave PR open [NO ACTION]
 ```
 
-Selecting option 1 means:
+Then render the mutually exclusive gate through the host-native **single-select structured choice UI** when available. In VS Code use the native question surface such as `vscode_askQuestions`. Offer:
+
+- `Merge and finalize delivery` `[HUMAN ACCEPTANCE + GITHUB/GIT WRITE]` — `RECOMMENDED`
+- `Review final PR diff first` `[READ ONLY]`
+- `Leave PR open` `[NO ACTION]`
+
+Use a numbered text list only when structured choice UI is unavailable.
+
+Selecting `Merge and finalize delivery` means:
 - the human accepts the final PR as observed,
 - merge is authorized using the repository-approved strategy,
 - applicable post-merge default-branch CI/policy may be observed/rechecked automatically,
@@ -247,7 +251,7 @@ Only after configured post-merge default-branch CI and any additional observable
 
 ## 10. Delivered-branch finalization
 
-For a normal short-lived delivered branch, option 1 at the merge gate already authorizes finalization. Do not ask a separate `Delete branch?` question.
+For a normal short-lived delivered branch, the `Merge and finalize delivery` gate choice already authorizes finalization. Do not ask a separate `Delete branch?` question.
 
 Preserve by default:
 - the configured default branch,
@@ -394,4 +398,4 @@ The optional learning handoff does not block or replace deployment readiness whe
 
 `/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision. After successful engineering completion it may prepare disposable learning workbenches and shows an optional learning handoff without creating another gate.
 
-`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.
+`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.

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

@@ -33,7 +33,7 @@ Resolve exact configured name, purpose/Production classification, placement, iso
 
 If `demo` exists, `/deploy demo` targets exactly `demo`. If `prod-east` has purpose `production`, `/deploy prod-east` remains a Production deployment even though the literal name differs.
 
-If no environment is named, enumerate configured environments and ask the human to choose; never silently default to Production. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
+If no environment is named, enumerate configured environments and ask the human to choose through host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`; never silently default to Production. Do not recommend an environment unless current project evidence or the user's stated deployment goal clearly supports one. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
 
 If the requested environment is missing or ambiguous, route to `/setup` rather than guessing.
 
@@ -48,7 +48,7 @@ Read only what is needed, including when present:
 - fresh setup-time environment-proof evidence for this workstation;
 - established application deployment facts.
 
-For package-managed generated POCs, prefer the repository-distributed launcher:
+For package-managed generated Projects, prefer the repository-distributed launcher:
 
 ```text
 tools/project-forge-deployment/project-forge-deploy.py
@@ -73,7 +73,7 @@ immutable application image/release policy
 smoke validation
 ```
 
-When a bounded choice is useful, provide a small recommended menu plus `Other / specify` and `Not sure — recommend one`.
+When a bounded choice is useful, follow `INTERACTIVE_SESSION_GUIDE.md`: use host-native structured choice UI when available, single-select for mutually exclusive values and multi-select only when several simultaneous selections are valid. Keep `Other / specify` or free-text available when the choices may be incomplete. Recommend at most one option, only when evidence or a clear engineering tradeoff supports it, and explain why briefly; otherwise show the choices without a recommendation. Record only the human's selected/confirmed answer.
 
 Once these facts are durably established, later deployments should be routine rather than repeating onboarding.
 

package/assets/generated/core/core/skills/deployment-readiness/SKILL.md

@@ -171,7 +171,7 @@ select exact project-defined environment
 → /deploy <environment>
 ```
 
-For remote placement, reuse valid existing target access rather than creating duplicate credentials simply because another POC/environment uses the same machine.
+For remote placement, reuse valid existing target access rather than creating duplicate credentials simply because another Project/environment uses the same machine.
 
 ## 6. Read-only status
 

package/assets/generated/core/core/skills/grill-with-docs/SKILL.md

@@ -34,7 +34,7 @@ Ask one material question at a time and challenge:
 - architecture/operational tradeoffs,
 - testability.
 
-When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
+When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. Use host-native single-select UI for mutually exclusive alternatives when available, and multi-select only when several choices may be valid together. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
 
 Cadence:
 
@@ -66,15 +66,13 @@ For local-document models, common homes are:
 
 Invocation alone does not imply broad document-write permission.
 
-When document changes are needed, present a bounded choice such as:
+When document changes are needed, present a bounded **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:
 
-```text
-1. Continue grilling only [READ ONLY]
-2. Reconcile resolved decisions during this session [MODIFIES DOCS]
-3. Stop [NO ACTION]
-```
+- `Continue grilling only` `[READ ONLY]`
+- `Reconcile resolved decisions during this session` `[MODIFIES DOCS]`
+- `Stop` `[NO ACTION]`
 
-After option 2 is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
+Use a numbered text list only when structured choice UI is unavailable. After `Reconcile resolved decisions during this session` is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
 
 Pause only when a new answer would change higher-level approved scope, contradict another authority/ADR, or require a new cross-cutting decision.
 

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -70,7 +70,7 @@ When deterministic setup passes but human workspace acceptance is still needed,
 
 When the workspace is accepted and the first approved work item is clear, recommend `/start-work <ID>`.
 
-If the developer wants the broader status instead of one action, offer `/progress` as a read-only option.
+If the developer wants the broader status instead of one action, offer `/progress` as a read-only choice.
 
 ## 3. Engineering/delivery states
 
@@ -111,14 +111,13 @@ CURRENT STATE
 RECOMMENDED NEXT STEP
 <one action and why>
 
-OPTIONS
-1. ... [READ ONLY]
-2. ... [MODIFIES FILES]
-3. ... [GIT + GITHUB WRITE]
-4. Stop [NO ACTION]
+CHOICES
+<only relevant bounded actions, rendered through structured choice UI when available>
 ```
 
-Only show relevant options. `/next-step` orients; it does not become another workflow database.
+When there is more than one relevant action, use the host's native **single-select structured choice UI** following `INTERACTIVE_SESSION_GUIDE.md`. In VS Code, use the question surface such as `vscode_askQuestions` when available. Keep consequence labels visible, mark the recommended choice where evidence supports one, and include `Other / specify` or free-text only when the action space may be incomplete. Use multi-select only for an explicitly multi-action workflow; ordinary `/next-step` choices are mutually exclusive.
+
+A textual numbered `OPTIONS` list is only the fallback when no structured choice UI is available. Only show relevant choices. `/next-step` orients; it does not become another workflow database.
 
 For an unprepared generated workspace, a good result is simply:
 
@@ -128,12 +127,10 @@ Local setup has not been completed on this computer.
 
 RECOMMENDED NEXT STEP
 /setup
-
-OPTIONS
-1. /progress [READ ONLY]
-2. Stop [NO ACTION]
 ```
 
+If useful, offer `/progress` `[READ ONLY]` and `Stop` `[NO ACTION]` through the structured selector; do not print a numbered menu in normal VS Code use.
+
 ## 5. Optional documentation and learning choices
 
 When implementation is stable enough to understand or document, `/next-step` may offer these choices without making them gates:
@@ -147,6 +144,8 @@ When implementation is stable enough to understand or document, `/next-step` may
 /system-lab [changes <work-item>]
 ```
 
+If the human is being asked to select one of these bounded next actions, use the same single-select structured-choice rule. The command list above is descriptive, not a required numbered menu.
+
 Prefer `/docs` for the coherent project briefing/document map, `/code-walkthrough` for implementation flow, `/db-lab` for concrete schema/query/index/ORM evidence, and `/system-lab` for architecture/runtime/failure/scale evidence.
 
 Safe generated projections may be prepared automatically. Do not silently rewrite project-owned prose, accept an ADR, or make learning mandatory before `/deliver` unless the approved work item explicitly requires it.

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

@@ -1,6 +1,6 @@
 ---
 name: progress
-description: "Read-only developer-facing progress view across POC creation, this workspace instance, work-item/delivery state, and exact project-defined environment capabilities."
+description: "Read-only developer-facing progress view across Project creation, this workspace instance, work-item/delivery state, and exact project-defined environment capabilities."
 argument-hint: "[optional work-item ID or environment]"
 user-invocable: true
 disable-model-invocation: true

package/assets/generated/core/core/skills/project-forge-update/SKILL.md

@@ -124,7 +124,7 @@ For a Bootstrap-generated consumer, also preview the companion generated-consume
 
 ## 5. Present one bounded update choice
 
-When the exact target package plan and any generated-consumer companion plan are safe, present:
+When the exact target package plan and any generated-consumer companion plan are safe, show the reviewed evidence:
 
 ```text
 PROJECT FORGE UPDATE READY
@@ -137,13 +137,17 @@ Core: <old> → <new>
 Deployment: <old> → <new> / unchanged
 Generated consumer metadata: <not present / coherent update planned>
 Managed drift/conflicts: NONE
-
-1. Apply the exact Project Forge package update [GIT + FILE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
-Choosing option 1 authorizes only:
+Then use the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Offer:
+
+- `Apply the exact Project Forge package update` `[GIT + FILE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
+Use a numbered text menu only when structured choice UI is unavailable.
+
+Choosing `Apply the exact Project Forge package update` authorizes only:
 
 - creation/switch to one repository-appropriate short-lived update branch when needed;
 - exact target package apply;

package/assets/generated/core/core/skills/pull-latest/SKILL.md

@@ -49,21 +49,25 @@ Never use `reset --hard`, force-push, merge, or rebase as part of `/pull-latest`
 
 ## 3. Choose the update target
 
+When the user must choose an update action, use the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Use a numbered text menu only when structured choice UI is unavailable.
+
 If the human supplied a branch, use that branch as the requested target when it can be resolved safely.
 
-If no branch was supplied and the current branch is the default branch, present:
+If no branch was supplied and the current branch is the default branch, show:
 
 ```text
 PULL LATEST READY
 
 Current branch: <branch>
 Working tree: CLEAN
-
-1. Refresh remote state and pull latest <branch> [GIT WRITE] — recommended
-2. Stop [NO ACTION]
 ```
 
-If no branch was supplied and the current branch is a non-default branch, present:
+Then offer:
+
+- `Refresh remote state and pull latest <branch>` `[GIT WRITE]` — `RECOMMENDED`
+- `Stop` `[NO ACTION]`
+
+If no branch was supplied and the current branch is a non-default branch, show:
 
 ```text
 PULL LATEST READY
@@ -71,13 +75,15 @@ PULL LATEST READY
 Current branch: <branch>
 Default branch: <default>
 Working tree: CLEAN
-
-1. Refresh and pull the current branch [GIT WRITE]
-2. Switch to the default branch and pull latest [GIT WRITE] — recommended for returning to baseline
-3. Stop [NO ACTION]
 ```
 
-Only the selected option authorizes fetch/switch/pull mechanics for the selected branch.
+Then offer:
+
+- `Refresh and pull the current branch` `[GIT WRITE]`
+- `Switch to the default branch and pull latest` `[GIT WRITE]` — `RECOMMENDED` when returning to baseline
+- `Stop` `[NO ACTION]`
+
+Only the selected choice authorizes fetch/switch/pull mechanics for the selected branch.
 
 ## 4. Refresh remote state
 

package/assets/generated/core/core/skills/refine-requirements/SKILL.md

@@ -113,22 +113,24 @@ STATUS
 <DRAFT / APPROVED / external status / not represented locally>
 ```
 
-Then present only relevant choices, for example:
+Then present only relevant actions as a **single-select structured choice** when the host supports it. In VS Code, use the native question surface such as `vscode_askQuestions` rather than printing a numbered menu. Conceptual choices may include:
 
-```text
-1. Review outcomes [READ ONLY]
-2. Review rules [READ ONLY]
-3. Review acceptance scenarios [READ ONLY]
-4. Refine identified gaps [MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]
-5. Grill an unresolved decision [READ ONLY]
-6. Review full requirements/work item [READ ONLY]
-7. Approve local requirements when applicable [REQUIREMENTS GATE]
-8. Stop [NO ACTION]
-```
+- `Review outcomes` `[READ ONLY]`
+- `Review rules` `[READ ONLY]`
+- `Review acceptance scenarios` `[READ ONLY]`
+- `Refine identified gaps` `[MODIFIES DOCS or PROPOSED EXTERNAL UPDATE]`
+- `Grill an unresolved decision` `[READ ONLY]`
+- `Review full requirements/work item` `[READ ONLY]`
+- `Approve local requirements` `[REQUIREMENTS GATE]` when applicable
+- `Stop` `[NO ACTION]`
+
+Make a recommendation only when current requirement evidence or a clear engineering tradeoff supports one. If so, mark exactly one choice with the host's `recommended` indicator and briefly explain why. If there is no clear basis, show the choices without a recommendation. The selected answer, not the recommendation, controls what the session does or records.
+
+If the host has no structured choice UI, present the same relevant choices as a concise numbered text fallback and accept the number, label, or free-form intent. Do not use the numbered fallback as the normal VS Code path.
 
 ## 5. Active refinement session
 
-Once the human selects a modifying refinement option, enter a bounded continuous session:
+Once the human selects a modifying refinement choice, enter a bounded continuous session:
 
 ```text
 ask one material requirement question
@@ -139,7 +141,26 @@ ask one material requirement question
 → next material question
 ```
 
-For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+For bounded requirement decisions such as lifecycle policy, validation behavior, destructive/reversible handling, or a small set of credible alternatives, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Render mutually exclusive alternatives through host-native **single-select** controls when available. Use multi-select only when the requirement genuinely permits multiple simultaneous selections. Keep `Other / specify` or free-text available when the option set may be incomplete. Keep outcome wording, workflow descriptions, acceptance intent, and other human-authored framing open-ended when predefined choices would constrain the requirement.
+
+Recommendation behavior follows the shared guide: recommend at most one option, only when evidence/tradeoffs support it; give a concise rationale; never record the recommendation as accepted until the human selects or confirms it; and honor a `no recommendation` request for that question only.
+
+Example of a supported recommendation:
+
+```text
+Decision: How should a browser-to-real-SQLite path be proven for a narrowly scoped work item?
+
+Choices:
+- Integration test against real SQLite
+- Browser smoke check through the API
+- Both
+- Other / specify
+
+Recommendation: Both
+Why: one real-SQLite integration test proves the persistence path and one browser smoke check proves the browser/API path without implying a broad end-to-end suite.
+```
+
+Treat this as advice for the human to accept, change, or replace. Do not record `Both` as a requirement until the human selects or confirms it.
 
 Do not ask after each answer whether to update.
 
@@ -162,7 +183,7 @@ Stop automatic reconciliation when an answer would:
 - require a cross-cutting architecture decision,
 - remain too ambiguous to record faithfully.
 
-Then present a small explicit choice.
+Then present a small explicit choice using the same host-native structured-choice rule. Keep the question open-ended instead when the human needs to explain or reframe the conflict in their own words.
 
 ## 7. Approval gate
 
@@ -175,7 +196,7 @@ APPROVED
 
 Human approval is explicit. Do not infer approval from review/planning/implementation.
 
-Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`.
+Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`. When the host offers structured choices, render this approval gate as a single-select action, not a numbered chat menu.
 
 External work-item status/approval follows the external team's conventions; Project Forge must not fabricate a local approval state.
 
@@ -198,7 +219,7 @@ Authority/status:
 <source and status>
 ```
 
-Then offer review, more grilling/refinement, approval when applicable, or stop.
+Then offer review, more grilling/refinement, approval when applicable, or stop using the same structured-choice-first rule.
 
 ## 9. Stop boundary
 

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

@@ -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 POC.
+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.
 
 Normal first use is simply:
 
@@ -107,7 +107,7 @@ Each workstation normally owns independent local development data. Reproduce sch
 
 ## 4. Establish/sync the developer's personal Project Forge profile
 
-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 POC or workstation.
+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.
 
 First inspect profile status and authenticated GitHub login. If the expected private repository is missing, tell the developer what will happen before writing:
 
@@ -138,26 +138,25 @@ If GitHub is temporarily unavailable, otherwise-ready local development remains
 
 After local readiness/profile state is understood, show the environments that this workstation can be prepared to use.
 
-Prefer a multi-select/checkbox-style interaction when the surface supports it. The conceptual shape is:
+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.
 
-```text
-SET UP THIS WORKSTATION FOR
+Conceptual choices are:
 
-[x] Local development — recommended
-[ ] Staging
-[ ] Production
-[ ] <other project-defined environment, e.g. Demo>
-[ ] Other / define another environment
-```
+- `Local development`
+- each existing project-defined environment from current topology
+- `Other / define another environment`
+
+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.
+
+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.
 
 Rules:
 
-- Local development is the recommended/default initial selection.
 - 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.
-- Free-form selection remains valid when checkbox UI is unavailable.
 - 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.
 
 ### Topology source of truth
 
@@ -171,7 +170,7 @@ Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fa
 
 `PROJECT_BOOTSTRAP.json` is generation/provenance evidence and should not be casually rewritten merely because a developer adds an environment later.
 
-If an older POC 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.
+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.
 
 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.
 
@@ -188,7 +187,7 @@ Isolation ....... <project/catalog-supported option>
 Exposure ........ <project/catalog-supported option>
 ```
 
-Provide recommended choices from the existing project topology/catalog and always allow `Other / specify` or `Not sure — recommend one` where appropriate.
+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.
 
 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:
 
@@ -221,7 +220,7 @@ If host prerequisites cannot yet be prepared automatically, report the exact pre
 
 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 POC 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 that should:
 
 ```text
 acquire a small stable probe image on this workstation
@@ -263,19 +262,23 @@ If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim
 
 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:
+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.
-
-1. Run Production environment proof
-2. Verify access/readiness only
-3. Skip this environment for now
 ```
 
+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
@@ -346,7 +349,7 @@ When the installed Deployment Kit exposes profile migration and this workstation
 
 Never ask the developer to paste passwords, PATs, private SSH keys, or other credentials into chat.
 
-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 POC repository or portable profile.
+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.
 
 ## 13. Relationship to other Project Forge commands