@miller-tech/uap 1.133.2 → 1.134.0

package/dist/config/settings-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-registry.d.ts","sourceRoot":"","sources":["../../src/config/settings-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,CAAC;AACzC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AACnE,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAE7C,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,cAAc,GACd,SAAS,GACT,SAAS,GACT,QAAQ,GACR,aAAa,GACb,eAAe,GACf,eAAe,GACf,SAAS,GACT,QAAQ,GACR,UAAU,GACV,OAAO,GACP,WAAW,GACX,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,iBAAiB,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAC1C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,UAAU,EAAE,SAAS,eAAe,EAgBhD,CAAC;AAIF,eAAO,MAAM,QAAQ,EAAE,SAAS,UAAU,EA+RzC,CAAC;AAMF,4CAA4C;AAC5C,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE9D;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,UAAU,EAAE,CAEtE;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAGxD;AAED,uCAAuC;AACvC,wBAAgB,QAAQ,CAAC,EAAE,EAAE,iBAAiB,GAAG,eAAe,GAAG,SAAS,CAE3E"}

package/dist/config/settings-registry.js

@@ -0,0 +1,334 @@
+/**
+ * UAP Settings Registry — the single source of truth for every user-facing
+ * setting UAP exposes.
+ *
+ * This one catalog powers three things so they can never drift:
+ *   - `uap config` (list / get / set / explain / doctor)
+ *   - the `uap setup --profile custom` expert wizard
+ *   - the generated `docs/reference/CONFIGURATION_REFERENCE.md`
+ *
+ * Two kinds of setting:
+ *   - kind 'json' — a field in `.uap.json` (persistent, first-class). `path` is
+ *     the dotted location; `uap config set` writes it via modifyUapConfig.
+ *   - kind 'env'  — an environment variable. `target: 'proxyEnv'` persists to
+ *     `.uap/proxy.env` (loaded by the inference proxy); `target: 'shell'` is a
+ *     runtime toggle read from the process env by hooks/CLI, so `set` prints the
+ *     export line to add rather than pretending to persist it.
+ *
+ * Adding a setting here automatically surfaces it in the CLI, the wizard, and
+ * the docs. Keep descriptions plain-language (what it does) and recommendations
+ * actionable (what to pick and when).
+ */
+export const CATEGORIES = [
+    { id: 'delivery', title: 'Delivery & enforcement', blurb: 'Whether coding routes through `uap deliver` and how hard the gates block.' },
+    { id: 'verification', title: 'Verification gates', blurb: 'Proving generated code actually builds and runs before "done".' },
+    { id: 'routing', title: 'Model routing', blurb: 'Which model handles planning, execution, and review.' },
+    { id: 'recipes', title: 'Serving recipes & escalation', blurb: 'Confidence/fusion recipes and the judge model that grades a local model.' },
+    { id: 'memory', title: 'Memory', blurb: 'Short-term recall, long-term semantic memory, and pattern RAG.' },
+    { id: 'concurrency', title: 'Concurrency & model slots', blurb: 'How many agents/inference slots run in parallel before backpressure.' },
+    { id: 'collaboration', title: 'Multi-agent collaboration', blurb: 'The shared coordination board and file-overlap protection.' },
+    { id: 'orchestration', title: 'Orchestrator & hands-free', blurb: 'Long-task autonomy: decompose, resume, and loop-to-100%.' },
+    { id: 'reactor', title: 'Reactor (auto-apply)', blurb: 'Per-prompt injection of the matching experts, skills, and patterns.' },
+    { id: 'design', title: 'Design system', blurb: 'DESIGN.md interrogation and the hard token gate for UI work.' },
+    { id: 'worktree', title: 'Worktree workflow', blurb: 'Branch-per-feature isolation and auto-cleanup.' },
+    { id: 'proxy', title: 'Inference proxy tuning', blurb: 'Guardrails and context limits for a local model behind the proxy.' },
+    { id: 'dashboard', title: 'Dashboard', blurb: 'The live analytics server and its mutation token.' },
+    { id: 'optimization', title: 'Token & time optimization', blurb: 'Context budgets, caching, batching, and parallelism.' },
+    { id: 'general', title: 'General', blurb: 'Project metadata and CLI behavior.' },
+];
+// A tuned local model with real gates is the reference environment for the
+// recommendations below; cloud-model users can relax the guardrail-heavy knobs.
+export const SETTINGS = [
+    // ── Delivery & enforcement ────────────────────────────────────────────────
+    {
+        key: 'delivery.enforcement', kind: 'json', type: 'enum', enumValues: ['block', 'advisory', 'off'],
+        default: 'block', category: 'delivery',
+        description: 'How the delivery gate treats a direct source edit outside `uap deliver`. `block` refuses it (exit 2), `advisory` warns but allows, `off` disables the gate. (The `UAP_ENFORCE_DELIVERY` env var overrides this at runtime.)',
+        recommendation: '`block` for hands-free/local-model work so every change is gated and verified; `advisory` when a capable human/Opus is driving and you want warnings without friction.',
+    },
+    {
+        key: 'delivery.localMode', kind: 'json', type: 'enum', enumValues: ['advisory', 'deliver', 'block'],
+        default: 'advisory', category: 'delivery',
+        description: 'How local-model sessions are routed through delivery. `deliver` runs builds through the convergence loop; `block` forbids raw edits; `advisory` warns.',
+        recommendation: '`deliver` when a local model does the writing (routes it through the verified loop); `advisory` for exploratory work.',
+    },
+    {
+        key: 'UAP_ENFORCE_DELIVERY', kind: 'env', type: 'enum', enumValues: ['block', 'advisory', 'off'],
+        default: 'block', category: 'delivery', target: 'shell',
+        description: 'Runtime override of the delivery gate read by the hooks/enforcers from the shell env. Takes precedence over `delivery.enforcement`.',
+        recommendation: 'Leave UNSET so it defaults to `block`. Exporting `advisory` globally leaks into every shell and silently disables the gate + the delivery-enforcement tests — set it inline per-command if you must.',
+    },
+    {
+        key: 'UAP_DELIVER_BYPASS', kind: 'env', type: 'boolean', default: false, category: 'delivery', target: 'shell',
+        description: 'When set to 1 for a single command, exempts that one sanctioned manual edit from the delivery gate.',
+        recommendation: 'Use inline (`UAP_DELIVER_BYPASS=1 <cmd>`) for a one-off edit; never export it.',
+    },
+    // ── Verification gates ────────────────────────────────────────────────────
+    {
+        key: 'delivery.runtimeVerify', kind: 'json', type: 'boolean', default: false, category: 'verification',
+        description: 'Installs the runtime-verify Stop-hook: at end of turn it actually runs the changed code (headless / vm-dom / child-process) and blocks stopping on a genuine runtime failure.',
+        recommendation: 'Enable for any project with a runnable artifact — it catches "declared done but never ran". Safe on empty projects (it skips when nothing is runnable).',
+    },
+    {
+        key: 'UAP_VERIFY_ON_STOP', kind: 'env', type: 'boolean', default: true, category: 'verification', target: 'shell',
+        description: 'Master switch for the runtime execution gate in the Stop hook. `0` bypasses it.',
+        recommendation: 'Leave on (default). Set `0` only to unblock a session where the runtime gate misfires.',
+    },
+    // ── Model routing ─────────────────────────────────────────────────────────
+    {
+        key: 'multiModel.enabled', kind: 'json', type: 'boolean', default: false, category: 'routing',
+        description: 'Turns on multi-model routing (distinct planner/executor/reviewer models) instead of a single model for everything.',
+        recommendation: 'Enable to pair a cheap local executor with a strong cloud reviewer. Configure via `uap model routing use <preset>`.',
+    },
+    {
+        key: 'multiModel.routingStrategy', kind: 'json', type: 'enum',
+        enumValues: ['cost-optimized', 'performance-first', 'balanced', 'adaptive'],
+        default: 'balanced', category: 'routing',
+        description: 'How the router trades cost against capability when picking a model per task.',
+        recommendation: '`cost-optimized` for local-first setups, `performance-first` for all-cloud hot paths, `balanced`/`adaptive` otherwise.',
+    },
+    {
+        key: 'ANTHROPIC_PASSTHROUGH_MODELS', kind: 'env', type: 'string', default: '', category: 'routing', target: 'proxyEnv',
+        description: 'Comma-separated model IDs the proxy forwards to Anthropic instead of serving locally. The sentinel `__local_only__` forces every model ID onto the local Qwen.',
+        recommendation: 'Set automatically by `uap model routing use`. Use `__local_only__` for a fully offline setup; list cloud IDs for a hybrid local+cloud routing preset.',
+    },
+    // ── Serving recipes & escalation ──────────────────────────────────────────
+    {
+        key: 'recipes.enabled', kind: 'json', type: 'boolean', default: false, category: 'recipes',
+        description: 'Enables serving-layer recipes (confidence escalation, fusion, ratings) in front of the local model.',
+        recommendation: 'Enable for a local model when you have a stronger judge model available — it materially lifts output quality.',
+    },
+    {
+        key: 'recipes.recipe', kind: 'json', type: 'enum',
+        enumValues: ['auto', 'single', 'confidence', 'fusion', 'ratings', 'remom'],
+        default: 'auto', category: 'recipes',
+        description: 'Which recipe to apply. `confidence` escalates only low-confidence turns to the judge; `fusion` samples N and judges; `auto` picks per-signal.',
+        recommendation: '`auto` is the safe default; `confidence` for the best cost/quality trade when the judge is expensive.',
+    },
+    {
+        key: 'recipes.confidenceThreshold', kind: 'json', type: 'number', min: 0, max: 1, default: 0.5, category: 'recipes',
+        description: 'Below this confidence, a turn is escalated to the judge model.',
+        recommendation: '0.5 to start; raise toward 0.7 to escalate more often (higher quality, higher cost).',
+    },
+    {
+        key: 'recipes.fusionN', kind: 'json', type: 'number', int: true, min: 2, max: 6, default: 3, category: 'recipes',
+        description: 'How many candidate samples the fusion recipe generates before the judge picks/merges.',
+        recommendation: '3 balances quality and cost; 5 for hard tasks if you can afford the samples.',
+    },
+    {
+        key: 'recipes.allowSelfJudge', kind: 'json', type: 'boolean', default: false, category: 'recipes',
+        description: 'Allows the generating model to also act as its own judge (generator == evaluator).',
+        recommendation: 'Keep `false` — a distinct, stronger judge is what adds the lift. Only allow self-judge if no separate judge is available.',
+    },
+    {
+        key: 'recipes.judge.model', kind: 'json', type: 'string', default: null, category: 'recipes',
+        description: 'The model ID used to grade/escalate. Must be distinct from and stronger than the executor to help.',
+        recommendation: 'Point at your strongest available model (e.g. an Opus/Sonnet cloud ID) even if the executor is local.',
+    },
+    {
+        key: 'PROXY_ESCALATE_API_KEY', kind: 'env', type: 'string', default: null, category: 'recipes', target: 'proxyEnv', secret: true,
+        description: 'API key for the judge/escalation model endpoint.',
+        recommendation: 'Store only in `.uap/proxy.env` (chmod 600) — never in `.uap.json`. `uap config set` writes it there.',
+    },
+    // ── Memory ────────────────────────────────────────────────────────────────
+    {
+        key: 'memory.longTerm.enabled', kind: 'json', type: 'boolean', default: true, category: 'memory',
+        description: 'Enables long-term semantic memory (vector recall across sessions) via Qdrant.',
+        recommendation: 'Keep on — cross-session recall is a core value. Requires a running Qdrant (`uap memory start`).',
+    },
+    {
+        key: 'memory.longTerm.provider', kind: 'json', type: 'enum',
+        enumValues: ['qdrant', 'chroma', 'pinecone', 'github', 'qdrant-cloud', 'serverless', 'none'],
+        default: 'qdrant', category: 'memory',
+        description: 'The long-term memory backend.',
+        recommendation: '`qdrant` (local) for privacy/speed; `qdrant-cloud` or `github` if you want memory to follow you across machines.',
+    },
+    {
+        key: 'memory.shortTerm.maxEntries', kind: 'json', type: 'number', default: 50, category: 'memory',
+        description: 'How many recent short-term entries are retained/injected per session.',
+        recommendation: '50 is a good default; raise for long, context-heavy sessions if token budget allows.',
+    },
+    {
+        key: 'memory.patternRag.enabled', kind: 'json', type: 'boolean', default: false, category: 'memory',
+        description: 'Enables pattern RAG — semantic retrieval of the 23 execution patterns to steer the agent.',
+        recommendation: 'Enable for local models (patterns compensate for weaker planning); optional for frontier models.',
+    },
+    {
+        key: 'QDRANT_URL', kind: 'env', type: 'string', default: 'http://localhost:6333', category: 'memory', target: 'shell',
+        description: 'Qdrant endpoint for long-term/pattern memory.',
+        recommendation: 'Leave default for local Qdrant; point at your cloud cluster URL for `qdrant-cloud`.',
+    },
+    {
+        key: 'QDRANT_API_KEY', kind: 'env', type: 'string', default: null, category: 'memory', target: 'shell', secret: true,
+        description: 'API key for a cloud Qdrant cluster.',
+        recommendation: 'Only needed for `qdrant-cloud`. Keep it in your shell env / secret store, not in `.uap.json`.',
+    },
+    // ── Concurrency & model slots ─────────────────────────────────────────────
+    {
+        key: 'modelConcurrency.slots', kind: 'json', type: 'number', int: true, min: 1, default: null, category: 'concurrency',
+        description: 'How many inference slots the local server exposes; the lease system caps parallel agents to this.',
+        recommendation: 'Set to your llama.cpp `--parallel` value so fan-out never exhausts the server. Leave null to auto-probe.',
+    },
+    {
+        key: 'modelConcurrency.headroom', kind: 'json', type: 'number', int: true, min: 0, default: null, category: 'concurrency',
+        description: 'Slots to hold back from the budget so the interactive session never starves behind background agents.',
+        recommendation: 'Reserve 1 on small servers so foreground work stays responsive.',
+    },
+    {
+        key: 'modelConcurrency.adaptive', kind: 'json', type: 'boolean', default: true, category: 'concurrency',
+        description: 'AIMD backpressure: shrinks the effective slot budget on exhaustion signals (429/timeouts) and recovers over time.',
+        recommendation: 'Keep on — it prevents overload cascades when many agents run at once.',
+    },
+    {
+        key: 'UAP_MAX_PARALLEL', kind: 'env', type: 'number', default: 4, category: 'concurrency', target: 'shell',
+        description: 'Upper bound on parallel agent/tool fan-out regardless of slot budget.',
+        recommendation: 'Match to CPU/GPU capacity; 4 is a safe default, lower it on constrained hosts.',
+    },
+    // ── Multi-agent collaboration ─────────────────────────────────────────────
+    {
+        key: 'collaboration.mode', kind: 'json', type: 'enum', enumValues: ['auto', 'always', 'off'],
+        default: 'auto', category: 'collaboration',
+        description: 'The shared coordination board + live file-overlap protection. `always` injects the board every turn; `auto` only when peers are active; `off` disables it.',
+        recommendation: '`auto` for solo work, `always` when multiple agents/worktrees run concurrently so they compound instead of colliding.',
+    },
+    {
+        key: 'coordination.deployBatching', kind: 'json', type: 'boolean', default: true, category: 'collaboration',
+        description: 'Batches git/deploy actions across agents to avoid conflicting concurrent pushes.',
+        recommendation: 'Keep on for multi-agent setups.',
+    },
+    // ── Orchestrator & hands-free ─────────────────────────────────────────────
+    {
+        key: 'handsfree.enabled', kind: 'json', type: 'boolean', default: false, category: 'orchestration',
+        description: 'Forces any model to keep working until a multi-epic completion ledger is 100% done, instead of stopping early.',
+        recommendation: 'Enable for large autonomous builds; leave off for interactive/exploratory sessions.',
+    },
+    {
+        key: 'handsfree.intensity', kind: 'json', type: 'enum', enumValues: ['gentle', 'normal', 'aggressive'],
+        default: 'normal', category: 'orchestration',
+        description: 'How hard hands-free pushes back against early stops before the ledger is complete.',
+        recommendation: '`normal` for most work; `aggressive` for unattended overnight runs; `gentle` if the model over-persists on dead ends.',
+    },
+    {
+        key: 'UAP_HANDSFREE_STAGNATION_LIMIT', kind: 'env', type: 'number', default: 8, category: 'orchestration', target: 'shell',
+        description: 'Consecutive no-progress turns before hands-free breaks the loop instead of pushing on.',
+        recommendation: 'Lower (e.g. 5) if runs waste turns stuck; raise for genuinely long-horizon tasks.',
+    },
+    // ── Reactor ───────────────────────────────────────────────────────────────
+    {
+        key: 'reactor.enabled', kind: 'json', type: 'boolean', default: true, category: 'reactor',
+        description: 'Per-prompt injection of the experts, skills, and patterns that match what you just asked — so relevant capability is on the bench before the agent starts.',
+        recommendation: 'Keep on. Disable only to debug prompt bloat or measure the reactor\'s own contribution.',
+    },
+    // ── Design system ─────────────────────────────────────────────────────────
+    {
+        key: 'design.enabled', kind: 'json', type: 'boolean', default: false, category: 'design',
+        description: 'Turns on DESIGN.md: the agent interrogates and lints UI work against your design brief.',
+        recommendation: 'Enable for any project with a UI so design work starts from intent, not a guess.',
+    },
+    {
+        key: 'design.tokenGate', kind: 'json', type: 'boolean', default: false, category: 'design',
+        description: 'Hard-blocks UI edits that hardcode off-token colors or off-scale spacing.',
+        recommendation: 'Enable once your DESIGN.md tokens are stable — it keeps the UI on-system automatically.',
+    },
+    // ── Worktree workflow ─────────────────────────────────────────────────────
+    {
+        key: 'worktrees.enabled', kind: 'json', type: 'boolean', default: true, category: 'worktree',
+        description: 'Branch-per-feature isolation: edits happen in `.worktrees/NNN-slug/`, never the working tree, with auto-PR.',
+        recommendation: 'Keep on for any team or multi-agent workflow; it is the safety net against clobbering `main`.',
+    },
+    {
+        key: 'worktrees.branchPrefix', kind: 'json', type: 'string', default: 'feature/', category: 'worktree',
+        description: 'Prefix for auto-created worktree branches.',
+        recommendation: 'Match your team\'s branch convention (e.g. `feat/`, `fix/`).',
+    },
+    {
+        key: 'worktrees.autoCleanup', kind: 'json', type: 'boolean', default: true, category: 'worktree',
+        description: 'Removes a worktree automatically once its branch is merged/unchanged.',
+        recommendation: 'Keep on to avoid a pile of stale worktrees.',
+    },
+    // ── Inference proxy tuning (curated high-impact subset) ────────────────────
+    {
+        key: 'PROXY_CONTEXT_WINDOW', kind: 'env', type: 'number', default: 65536, category: 'proxy', target: 'proxyEnv',
+        description: 'The context window the proxy advertises/enforces for the local model. Must match the server\'s KV allocation.',
+        recommendation: 'Set to your llama.cpp per-slot context size. Too high overflows KV; too low truncates history.',
+    },
+    {
+        key: 'PROXY_CONCURRENCY_LIMIT', kind: 'env', type: 'number', default: null, category: 'proxy', target: 'proxyEnv',
+        description: 'Max concurrent upstream generations the proxy admits before queuing.',
+        recommendation: 'Match to the server\'s parallel slots so the proxy queues instead of overloading the model.',
+    },
+    {
+        key: 'PROXY_LOOP_BREAKER', kind: 'env', type: 'boolean', default: true, category: 'proxy', target: 'proxyEnv',
+        description: 'Breaks no-progress generation loops by forcing a single non-streaming call.',
+        recommendation: 'Keep on for local models — it is a core reliability guardrail.',
+    },
+    {
+        key: 'PROXY_STUCK_BREAK', kind: 'env', type: 'boolean', default: true, category: 'proxy', target: 'proxyEnv',
+        description: 'When the model self-reports "stuck" but keeps repeating the same failing tool, releases it to a prose exit.',
+        recommendation: 'Keep on for local models; harmless for cloud models (rarely triggers).',
+    },
+    {
+        key: 'PROXY_RECON_CONVERGENCE_THRESHOLD', kind: 'env', type: 'number', default: 40, category: 'proxy', target: 'proxyEnv',
+        description: 'After this many read-only (no-write) turns, the proxy forces synthesis/`deliver` so the model stops exploring forever.',
+        recommendation: '40 is balanced; lower it (e.g. 20) if local sessions over-explore before writing.',
+    },
+    {
+        key: 'PROXY_RECIPE', kind: 'env', type: 'enum', enumValues: ['auto', 'single', 'confidence', 'fusion', 'ratings', 'remom'],
+        default: 'auto', category: 'proxy', target: 'proxyEnv',
+        description: 'The serving recipe the proxy applies (mirror of `recipes.recipe`, consumed by the proxy process).',
+        recommendation: 'Keep in sync with `recipes.recipe`; `uap setup`/`uap config` write both.',
+    },
+    // ── Dashboard ─────────────────────────────────────────────────────────────
+    {
+        key: 'UAP_DASHBOARD_TOKEN', kind: 'env', type: 'string', default: null, category: 'dashboard', target: 'shell', secret: true,
+        description: 'The token required for dashboard policy-mutation routes (enable/disable/stage/level). Read routes stay open.',
+        recommendation: 'Set a strong token if the dashboard binds beyond localhost (`--host 0.0.0.0`); otherwise a generated per-session token is used.',
+    },
+    {
+        key: 'UAP_DASH_REFRESH_MS', kind: 'env', type: 'number', default: 2000, category: 'dashboard', target: 'shell',
+        description: 'Dashboard data refresh interval in milliseconds (floor 250).',
+        recommendation: '2000 is fine; lower for a more live feel at higher CPU cost.',
+    },
+    // ── Token & time optimization ─────────────────────────────────────────────
+    {
+        key: 'costOptimization.enabled', kind: 'json', type: 'boolean', default: true, category: 'optimization',
+        description: 'Enables token budgets, response caching, and embedding batching to cut token spend.',
+        recommendation: 'Keep on — it is free savings with no quality cost.',
+    },
+    {
+        key: 'timeOptimization.parallelExecution.maxParallelDroids', kind: 'json', type: 'number', default: 4, category: 'optimization',
+        description: 'Max expert droids run in parallel during a task.',
+        recommendation: 'Match to host capacity; 4 is a safe default.',
+    },
+    // ── General ───────────────────────────────────────────────────────────────
+    {
+        key: 'project.defaultBranch', kind: 'json', type: 'string', default: 'main', category: 'general',
+        description: 'The branch PRs target and worktrees branch from.',
+        recommendation: 'Set to your repo\'s default branch (`main` or `master`).',
+    },
+    {
+        key: 'UAP_NO_SELF_UPDATE', kind: 'env', type: 'boolean', default: false, category: 'general', target: 'shell',
+        description: 'Disables the automatic global-CLI version check/self-update on `uap setup`.',
+        recommendation: 'Set in CI or pinned environments where you manage the UAP version yourself.',
+    },
+];
+// ── Lookup helpers ──────────────────────────────────────────────────────────
+const BY_KEY = new Map(SETTINGS.map((s) => [s.key.toLowerCase(), s]));
+/** Case-insensitive exact lookup by key. */
+export function getSetting(key) {
+    return BY_KEY.get(key.toLowerCase());
+}
+/** All settings in a category, in registry order. */
+export function settingsByCategory(id) {
+    return SETTINGS.filter((s) => s.category === id);
+}
+/** Fuzzy match for `config get/set/explain` when the key isn't exact. */
+export function findSettings(query) {
+    const q = query.toLowerCase();
+    return SETTINGS.filter((s) => s.key.toLowerCase().includes(q));
+}
+/** The category metadata for an id. */
+export function category(id) {
+    return CATEGORIES.find((c) => c.id === id);
+}
+//# sourceMappingURL=settings-registry.js.map

package/dist/config/settings-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-registry.js","sourceRoot":"","sources":["../../src/config/settings-registry.ts"],"names":[],"mappings":"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"}

package/docs/INDEX.md

@@ -53,6 +53,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [Worktree Workflow](guides/WORKTREE_WORKFLOW.md) | Branch-per-feature isolation, auto-PR, enforcement |
 | [Sandbox](guides/SANDBOX.md) | Kernel-level (bubblewrap) write isolation — the boundary that survives `--dangerously-skip-permissions` |
 | [Policies](guides/POLICIES.md) | Executable policy gates that block non-compliant tool calls |
+| [**Policy Selection & Recommendations**](guides/POLICY_SELECTION.md) | Which policies to enable for your workflow — a recommended core + tailored sets by scenario; `uap policy recommend` ⭐ |
 | [Multi-Model Routing](guides/MULTI_MODEL.md) | Plan → route → execute across 7 model profiles |
 | [Droids & Skills](guides/DROIDS_AND_SKILLS.md) | 38 expert droids, 32 skills, the expert router |
 | [Deploy Batching](guides/DEPLOY_BATCHING.md) | Conflict-free batched git/deploy actions |
@@ -79,6 +80,7 @@ Full map: **[The UAP Delivery Pipeline](guides/DELIVERY_PIPELINE.md)**.
 | [Patterns](reference/PATTERNS.md) | The 23 Terminal-Bench patterns |
 | [Platforms](reference/PLATFORMS.md) | The 9 supported harnesses + support matrix |
 | [Configuration](reference/CONFIGURATION.md) | All config files and env vars |
+| [**Configuration Reference**](reference/CONFIGURATION_REFERENCE.md) | Every setting `uap config` exposes — what it does, default, and a recommendation (generated from the registry); `uap config list/explain/set/doctor/wizard` ⭐ |
 | [Database Schema](reference/DATABASE_SCHEMA.md) | SQLite databases + Qdrant collections |
 
 ## Integrations

package/docs/guides/POLICY_SELECTION.md

@@ -0,0 +1,98 @@
+# Policy Selection & Recommendations
+
+UAP ships ~33 executable policies (the [enforcer catalog](POLICIES.md)). You don't want all of them on for every project — you want the set that fits *your* workflow. This guide gives you a recommended core plus tailored add-ons by scenario, and the commands to apply them.
+
+> **Live version of this guide:** `uap policy recommend` (all scenarios) or `uap policy recommend <scenario>` (a tailored set with an install command). The recommendations here and in the CLI come from the same source (`src/config/policy-recommendations.ts`).
+
+## How policies work (the 20-second version)
+
+A policy is enforced by a hook → the enforcer inspects the tool call → it **allows (exit 0)** or **blocks (exit 2)**. Only `REQUIRED`-level policies hard-block; `RECOMMENDED`/`OPTIONAL` are advisory. Each enforcer also has an env kill-switch (e.g. `UAP_NO_WORKTREE`, `UAP_DELIVER_BYPASS`) so a human can override a single call — they're **cooperative guardrails**, not a sandbox. For a true write boundary, pair them with the [sandbox](SANDBOX.md). Full mechanics: [Policies](POLICIES.md).
+
+## Apply them
+
+```bash
+uap policy recommend                 # list the core set + all scenarios
+uap policy recommend team            # tailored set for a scenario + an install command
+uap policy install <slug>            # install one policy (attaches its enforcer)
+uap policy matrix                    # see everything installed + how to adjust it
+uap config wizard                    # interactive: pick a scenario, install in one step
+uap setup --profile custom           # baseline setup, then the wizard (config + policies)
+```
+
+## The core set — recommended for every project
+
+The safety floor. `uap setup` installs the delivery-enforcement + self-protect pieces automatically; the rest are one `uap policy install` away.
+
+| Policy | Why |
+|---|---|
+| `worktree-required` | Edits land in an isolated worktree, never the working tree. |
+| `delivery-enforcement` | Source changes route through the verified `deliver` loop. |
+| `enforcement-self-protect` | Agents cannot disable the gates that constrain them. |
+| `task-required` | Work is tied to a tracked task, not ad-hoc. |
+| `test-gate` | Changed code must pass tests before "done". |
+| `memory-before-plan` | The agent recalls prior decisions before re-deriving them. |
+| `workdir-scope` | Writes are contained to the project directory. |
+
+## Scenarios — add these on top of the core
+
+Pick the row that matches how you work. Each adds to the core set above.
+
+### Solo dev, local model
+*One person driving a local (llama.cpp/Qwen) model that needs strong guardrails.*
+
+`codebase-read-before-plan` · `validate-plan-before-build` · `mcp-router-first` · `local-build-before-push` · `ship-loop-gate` · `doc-live-over-report`
+
+Weaker models benefit most from "read before you plan", a lean context window, and converging to green before shipping.
+
+### Team / multi-agent
+*Multiple people or agents working the same repo concurrently.*
+
+`coord-overlap` · `expert-review-required` · `schema-diff-gate` · `session-memory-write` · `artifact-hygiene`
+
+The point is to stop agents colliding, surface contract changes for review, and capture learnings so peers compound them.
+
+### CI-gated delivery
+*Changes must survive a CI pipeline and controlled deploys.*
+
+`local-build-before-push` · `ship-loop-gate` · `merge-deploy-monitor-verify` · `schema-diff-gate`
+
+Fail fast locally, re-converge on red CI, and treat deploys as monitored + verified rather than fire-and-forget.
+
+### High autonomy / hands-free
+*Long unattended builds where the model must not cut corners.*
+
+`validate-plan-before-build` · `ship-loop-gate` · `artifact-hygiene` · `doc-live-over-report` · `codebase-read-before-plan`
+
+A wrong plan wastes an entire autonomous run — validate up front, grade the real system (not the model's optimism), and only end when the work is genuinely done.
+
+### Security-sensitive
+*Handling secrets, infrastructure, or regulated code.*
+
+`bearer-lockdown` · `schema-diff-gate` · `iac-parity` · `iac-plan-destruction-check`
+
+Block credential leaks, forbid silent permission/API-surface changes, and flag destructive infra plans before apply.
+
+### UI / design work
+*Projects with a front-end and a design system.*
+
+`design-token-gate` · `visual-verification`
+
+Keep UI edits on your design tokens/spacing and verify changes visually, not just by tests. Pair with [DESIGN.md](../design/UAP_REACTOR.md) and `uap config set design.enabled true`.
+
+## Tuning the level of any policy
+
+A policy's *level* decides whether it hard-blocks or just warns:
+
+```bash
+uap policy level <id> RECOMMENDED   # downgrade a REQUIRED gate to advisory
+uap policy level <id> REQUIRED      # promote an advisory to a hard block
+uap policy disable <id>             # turn it off entirely
+```
+
+Start stricter than you think you need — it's easier to relax a gate that's too noisy than to notice a class of mistakes a missing gate let through. Run `uap config doctor` to catch settings that quietly weaken the whole set (e.g. a leaked `UAP_ENFORCE_DELIVERY=advisory`).
+
+## See also
+
+- [Policies](POLICIES.md) — the full enforcer catalog + CLI reference
+- [Configuration Reference](../reference/CONFIGURATION_REFERENCE.md) — every setting `uap config` exposes
+- [Sandbox](SANDBOX.md) — the kernel-level write boundary that backs the cooperative gates