feat(routing): global defaults and guided setup wizard

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.16.0 — Unreleased
+
+- Add `guildhall-routing-setup`, a conversational wizard for global/project setup, settings changes, diagnosis and disabling.
+- Suggest shadow mode for new users and preview supported profiles, scope, outbound data and prerequisites before activation.
+- Ship complete independent quest/setup skills generated from shared routing resources, and verify both installation routes.
+
+## 0.15.0 — Unreleased
+
+- Add global per-host routing defaults, optional full project overrides and explicit opt-out.
+- Persist source-bound activation across projects and sessions with host/evidence checks, expiry and revocation.
+- Bundle offline configuration preview, preparation and status with atomic conflict-checked writes.
+- Preserve legacy policies, qualification and quest-local state; deleting a project policy now restores global inheritance.
+
 ## 0.14.0 — Unreleased
 
 - Make all 18 specialists eligible through explicit schema-v4 role allowlists.

CLAUDE.md

@@ -54,6 +54,11 @@ When editing `quest.md`, preserve this three-phase shape. Serializing the review
 
 ### Explicit dispatch settings and optional routing
 
+Resolve session/project/global defaults through the installed
+[global routing contract](plugin/skills/guildhall-quest/references/global-routing.md).
+Reuse unchanged source-bound approval with fresh host evidence; recheck each
+worker boundary. Setup writes stay outside Mordain's plan-only execution scope.
+
 Every native `Agent(...)` call includes a literal `model` argument. Resolve it
 through valid per-dispatch user choice → role override → activated routing →
 eligible roster/frontmatter baseline. Full host-supported IDs are permitted on
@@ -74,7 +79,7 @@ single helper used by native Claude and portable Claude/Codex. Absent/off policy
 skips Python and external calls. Shadow needs explicit activation, not adaptive
 qualification. Schema v4 makes all 18 specialists eligible for adaptive routing
 with an explicit role allowlist and reviewed role/category/host/profile evidence.
-No qualified profiles ship. Prepare project policy before the quest, outside Mordain's plan-only write scope. Any policy change requires
+No qualified profiles ship. Prepare global defaults or a project override before the quest, outside Mordain's plan-only write scope. Any policy change requires
 renewed activation. Serialize helper decisions and carry returned state across
 workers, even when the workers run concurrently. Keep test-author routing facts
 within its permitted handoff. Routing never changes reviewers, permissions,

README.md

@@ -1,7 +1,7 @@
 # Guildhall
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Plugin](https://img.shields.io/badge/plugin-v0.14.0-green.svg)](plugin/README.md)
+[![Plugin](https://img.shields.io/badge/plugin-v0.16.0-green.svg)](plugin/README.md)
 
 **Give a coding task to a team of AI specialists that writes tests, implements the
 change, reviews it and prepares a PR draft.**
@@ -19,8 +19,9 @@ code, tests, review evidence and a PR draft. Publishing a PR is a separate actio
 
 ## Install
 
-The commands below install Guildhall from its published main branch. **Version
-0.14.0 adds routing support for all 18 specialists, usage accounting and study tools.**
+The commands below install Guildhall from its published main branch. This branch
+prepares **0.16.0**, adding a conversational specialist-routing setup wizard
+alongside global defaults and persistent approvals; those changes reach the main install route after merge.
 Choose one route for your coding app. No repository clone, build or IDD
 installation is required.
 
@@ -62,8 +63,8 @@ Choose **project** to keep the skill with this project; choose **global** if you
 want it available across projects. Version `1.5.25` is the tested installer pin,
 not the Guildhall version.
 
-The repository contains one installable skill: `guildhall-quest`, including its
-workflow and role references. Standalone skills do not install Claude's native
+Choose `guildhall-quest` for coding workflows and `guildhall-routing-setup` for
+the optional conversational routing wizard. Each skill is independently installable. Standalone skills do not install Claude's native
 agents or hooks. After restarting your app, ask it to use `guildhall-quest` to
 prototype a small task. The `/guildhall:quest` examples below are native Claude
 plugin commands; skill-only installs use `guildhall-quest` instead.
@@ -121,8 +122,23 @@ existing model defaults without a Jev key or the routing Python runtime.
   when that role is explicitly enabled and independently qualified for its host,
   task category and objective. No qualified profiles ship with this release.
 
-An API key alone enables nothing. Prepare the project policy before starting a
-quest, then explicitly activate it. The [routing guide](docs/model-routing.md)
+To use the wizard, ask **“Set up Guildhall routing”** or invoke:
+
+```text
+$guildhall-routing-setup Set up model routing across my projects.
+```
+
+The wizard detects the host, asks short choices, previews settings and saves them
+after your selected action. New setup recommends shadow mode, which leaves worker
+models unchanged. It also handles changes, diagnosis and disabling routing. Native
+plugins include the skill; standalone users select it during installation.
+
+Configure routing once per host with [global defaults](plugin/skills/guildhall-quest/references/global-routing.md)
+in `~/.config/guildhall/routing.json` (or XDG_CONFIG_HOME). Approve the selected
+policy for all projects once; unchanged approvals persist across sessions. Optional
+`.guildhall/routing.json` project policies override it in full, and a project opt-out
+can disable routing. Deleting a project policy restores global inheritance.
+An API key alone enables nothing. The [routing guide](docs/model-routing.md)
 includes a setup prompt, safe smoke command, data-sharing details, receipts and
 disable instructions. The [role matrix and migration guide](plugin/skills/guildhall-quest/references/role-eligibility.md)
 explains how to enable one qualified role at a time. There are no measured Jev savings or live qualification
@@ -177,7 +193,9 @@ for evidence and remaining limits.
 
 Native Claude components live in `plugin/agents/`, `plugin/commands/` and
 `plugin/hooks/`. Portable sources live in `plugin/portable/`; the complete
-`plugin/skills/guildhall-quest/` bundle is generated by `scripts/build_portable.py`.
+`plugin/skills/` bundles are generated by `scripts/build_portable.py` from the
+portable quest source and `plugin/routing-setup/`. Shared routing tools have one
+canonical source and ship in both independently usable skills.
 Contributors use Python 3.12+; users do not need the build tooling to load the skill.
 
 ## License

docs/contributing-agents.md

@@ -19,7 +19,9 @@ not a quest invocation and does not automatically activate quest dispatch rules.
   into portable references. Host metadata is stripped; narrow substitutions adapt
   guidance, evidence, recovery and runbook contracts. These differences are
   intentional and must be reviewed whenever the native role contract changes.
-- `plugin/skills/guildhall-quest/`: generated complete bundle; never hand-edit.
+- `plugin/skills/`: generated complete quest and routing-setup bundles; never hand-edit.
+- `plugin/routing-setup/`: canonical conversational setup entry and flow. Shared
+  tools, schemas and routing references still come from `plugin/portable/`.
 - Three manifests: portable `plugin/plugin.json`, Codex
   `plugin/.codex-plugin/plugin.json`, Claude `plugin/.claude-plugin/plugin.json`.
   Keep identity and versions aligned. Claude's existing tier description remains
@@ -145,7 +147,7 @@ workers or claim synthetic savings as observed results. See the
 
 ## Distribution and versioning
 
-The current package version is 0.14.0; increment all three manifests for further
+The current package version is 0.16.0; increment all three manifests for further
 installer-visible changes. Existing native Claude agents/commands/hooks remain
 preserved. Never rewrite historical plans to claim newer evidence. No repository
 change implicitly installs personally, publishes a release or edits the separate
@@ -184,3 +186,9 @@ routing guide in `plugin/portable/references/model-routing.md`, then regenerate.
 
 Maintain `routing_usage.py` in the canonical portable scripts. Usage input schema
 1 is separate from routing schema2; v1 routing policy hashes are not rewritten.
+
+Maintain global policy resolution and approval persistence in
+`plugin/portable/scripts/routing_config.py` and `references/global-routing.md`.
+Configuration schemas have their own version; existing routing policy hashes
+and quest state semantics remain unchanged. Test using isolated user directories;
+never activate or install into a personal profile during packaging validation.

docs/installation.md

@@ -1,8 +1,8 @@
 # Guildhall installation and host support
 
-Version **0.14.0 is a release candidate**, available through the `main` commands
-below after merge. It includes all-role routing eligibility, usage/evidence/study tools, one complete
-`guildhall-quest` skill and native Codex metadata. Claude's `/guildhall:quest`, nineteen agent definitions
+Version **0.16.0 is a release candidate**, available through the `main` commands
+below after merge. It includes all-role routing eligibility, usage/evidence/study tools, independent
+`guildhall-quest` and `guildhall-routing-setup` skills and native Codex metadata. Claude's `/guildhall:quest`, nineteen agent definitions
 and hooks remain available. Choose one route per quest to avoid duplicate entry
 points. Guildhall works independently; IDD is optional. See
 [using Guildhall with IDD](../README.md#optional-use-with-idd) if you want to add
@@ -85,9 +85,12 @@ use `--global` instead of `--project` for updates.
 
 ```bash
 npx --yes skills@1.5.25 add GrillerGeek/guildhall --skill guildhall-quest --agent codex --copy --yes
+npx --yes skills@1.5.25 add GrillerGeek/guildhall --skill guildhall-routing-setup --agent codex --copy --yes
 npx skills@1.5.25 list --agent codex
 ```
 
+The second add command installs the optional setup wizard. Each skill can be
+installed alone; the wizard does not dispatch workers or require the quest skill.
 Look for `guildhall-quest` in the listing. Restart your coding app, then ask it
 to use `guildhall-quest` for a small prototype.
 This verifies discovery; executing a workflow still depends on the host's tools
@@ -103,7 +106,8 @@ npx skills@1.5.25 update guildhall-quest --project --yes
 
 This command uses the installer lockfile and detected project destinations.
 To retain an explicit target app and copy method, or repair an installed copy,
-repeat the full `add` command above instead. Restart the app afterward. Updates
+repeat the corresponding `add` command above instead. To update the setup wizard,
+use `update guildhall-routing-setup --project --yes` with the same installer. Restart the app afterward. Updates
 replace installed resources; keep project instructions in your project rather
 than editing the installed bundle.
 
@@ -120,15 +124,19 @@ npx skills@1.5.25 remove guildhall-quest --agent codex --yes
 npx skills@1.5.25 list --agent codex
 ```
 
-Removal was verified in single-host copy fixtures, preserving an unrelated
+To remove only the wizard, replace `guildhall-quest` with `guildhall-routing-setup`
+in the remove command. Configuration/approvals remain in their user-owned location.
+
+Removal of the quest skill was verified in single-host copy fixtures, preserving an unrelated
 skill. In projects sharing `.agents/skills` across hosts, a copy may remain for
 another host; inspect the listing and selected path rather than assuming success
 means every shared copy was deleted. Avoid `--all` when keeping other skills.
 
 ### Local sources and advanced discovery
 
 Replace `GrillerGeek/guildhall` with `/absolute/path/to/guildhall` or the direct
-`plugin/skills/guildhall-quest` directory to install local development files.
+`plugin/skills/guildhall-quest` or `plugin/skills/guildhall-routing-setup` directory
+to install that skill’s local development files.
 To inspect available skills without installing:
 
 ```bash
@@ -142,14 +150,29 @@ hooks are not installed by this route.
 
 ## Optional routing setup after installation
 
+With the wizard installed, restart the host and ask **“Set up Guildhall routing”**,
+or invoke `$guildhall-routing-setup` in Codex. It detects the executing host, offers
+global/project scope and a goal, checks profiles and prerequisites, then presents
+a plain-language proposal. You choose whether to save and enable shadow mode, save
+off, change choices or cancel. It never treats missing evidence as qualification
+or runs a paid test automatically. A returning user can ask the same skill to
+change, diagnose or disable routing.
+
+For manual setup or the wizard’s underlying contract:
+
 Restart the host after installing or updating. Locate the installed
 `guildhall-quest` directory containing `SKILL.md`, `resources/` and `scripts/`.
 Native Claude uses `${CLAUDE_PLUGIN_ROOT}/skills/guildhall-quest`; standalone and
 Codex paths depend on the selected installation scope. Use the installed bundle,
 not `plugin/portable`, which is an authoring source.
 
-Follow [the routing guide](model-routing.md) to prepare `.guildhall/routing.json`
-before a quest. Python **3.12+** is required only for the optional routing helper;
+Follow [global routing setup](../plugin/skills/guildhall-quest/references/global-routing.md)
+to prepare and approve one policy per host in `~/.config/guildhall/routing.json`
+(or the absolute XDG_CONFIG_HOME location). Projects inherit it without setup.
+Optional `.guildhall/routing.json` files replace those defaults; an explicit project
+opt-out disables routing. Removing a project policy restores global inheritance.
+Package updates and removal leave user configuration and approval files alone.
+The [routing guide](model-routing.md) covers qualification and outbound data. Python **3.12+** is required only for the optional routing helper;
 normal skill loading and off-mode dispatch do not need it. Native Claude's
 existing Python hooks retain their separate prerequisites. Set
 `TYPESAFE_API_KEY` in the environment of the terminal/process launching the host