oris-skills 2.2.1 → 2.2.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+- **Settings are per-project and tiny**: moved out of the user-global `~/.oris/settings.json` into `.oris-flow/settings.json`, holding only `orisFlow.responseStyle` (`standard`/`caveman`) and `orisFlow.artifactLanguage` (document language, default `en`). The installer no longer creates a settings file.
+- **Test profiles removed**: the whole profile/secret subsystem is gone — `defaultProfiles`, `profiles`, the adapter `profile` block and its env mappings, and the loop's profile-gating. Every project drives its own e2e/CI tooling; Oris stores no credentials.
+- **No UI-language setting**: chat, menus, and question labels follow the language the user writes (deduced from context); only generated documents use `artifactLanguage`.
+- **No refresh-policy setting**: map freshness is answered by the `headSha` anchor (`flow scan --check`); the advisory `refreshPolicy` field was dropped from the manifest and schema.
+- **Questions & subagents fire reliably**: conventions now bind a platform question call (Claude `AskUserQuestion`) as a tool call rather than optional chat text, and treat entering an Oris route as the explicit request to spawn scan subagents — so gates open their UI and setup fans out by default.
+
 ## 2.2.1 - 2026-07-07
 
 - **Loop roles are invisible to users**: the installer no longer writes `oris-loop-{executor,verifier,doctor,debriefer}` into `~/.cursor/agents/`, `~/.claude/agents/`, or `~/.codex/agents/` — they showed up as manually invocable subagents, but the loop orchestrator never spawns them by name (it passes each loop's `prompts/<role>.md` to a generic subagent). `agents/` stays in the repo as the canonical role definitions for development. Uninstall (and therefore reinstall/upgrade) now also removes adapters left behind by earlier versions.

package/README.md

@@ -91,9 +91,10 @@ Stop anything, anytime: `npx oris-skills loop chat --action stop`.
 
 ## Tuning
 
-Settings live in `~/.oris/settings.json` (`/oris-flow` → Setup → language & profiles):
-chat and document language (`en`/`it`), test profiles, and `responseStyle: "caveman"` —
-chat shrinks to maximum token density while documents and safety gates stay complete.
+Settings live in `.oris-flow/settings.json` (`/oris-flow` → Setup): document language
+(`artifactLanguage`, default `en`) and `responseStyle` (`standard`/`caveman`, where
+caveman shrinks chat to maximum token density while documents and safety gates stay
+complete). Chat language is deduced from your messages, not configured.
 
 ## Repository layout
 

package/docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records
+
+Decisions agents must not re-litigate. Format: `NNNN-short-title.md`.
+
+Each ADR: context, decision, consequences. See `docs/architecture.md` for current principles.

package/docs/distribution.md

@@ -14,13 +14,12 @@ The installer detects Cursor / Claude Code / Codex from `~/.cursor`, `~/.claude`
 
 ```text
 ~/.oris/oris-skills/        bundle: scripts, skills, references, agents, docs
-~/.oris/settings.json       user settings (created only if missing)
 ~/.cursor/skills/<name>/    Cursor skills (marker-managed)
 ~/.claude/skills/<name>/    Claude Code skills (marker-managed)
 ~/.codex/prompts/<name>.md  Codex prompts pointing to the bundled SKILL.md
 ```
 
-Project assets live only in each repository's `.oris-flow/` (adapter, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `npx oris-skills loop bootstrap`.
+Project assets live only in each repository's `.oris-flow/` (adapter, settings, loops, runtime) plus thin hook wrappers in `.cursor/hooks/` and `.claude/hooks/` written by `npx oris-skills loop bootstrap`.
 
 ## Uninstall / reinstall
 

package/docs/user-guide.md

@@ -42,4 +42,4 @@ npx oris-skills reinstall
 ```
 
 Uninstall removes only Oris-owned paths (including legacy locations); preview with `--dry-run`.
-Settings (language, test profiles, `responseStyle: caveman` for ultra-short chat): `~/.oris/settings.json`, edited via `/oris-flow` → Setup.
+Settings (`artifactLanguage` for document language, `responseStyle: caveman` for ultra-short chat): `.oris-flow/settings.json`, edited via `/oris-flow` → Setup. Chat language is deduced from context, not configured.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oris-skills",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Oris Skills: one entry point (/oris-flow), guided discovery-to-implementation flow, and self-tuning verified loops for Cursor, Claude Code, and Codex.",
   "license": "MIT",
   "author": "Davide Baldassarre",

package/references/conventions.md

@@ -26,9 +26,18 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
 
 ## Questions
 
-- ASK with the platform question UI (Cursor `AskQuestion`, Claude `AskUserQuestion`); ELSE ask plainly in chat.
+- ASK through the platform's question tool — Claude `AskUserQuestion`, Cursor `AskQuestion`
+  (Plan Mode). A question turn = ONE call to it. Chat text is a fallback, NOT a choice: use
+  it ONLY when no such tool is available (e.g. Cursor Agent Mode) or the question cannot fit
+  the tool's schema (open-ended, or more options than it allows) — then present the options
+  as a lettered list.
+- Oris gates and interview questions ALWAYS qualify for the tool: the answer decides the
+  next step. NEVER skip the tool because an answer "looks like a sensible default".
+- FIT the schema: question tools cap the options (typically 4, meta-options included).
+  MORE options → split into a two-level question (category first) or use the deliberate
+  text fallback above.
 - ONE question per turn. Recommended answer FIRST.
-- ALWAYS include, localized to `uiLanguage`:
+- ALWAYS include, in the user's language:
   - `Explain the options` / `Spiega le opzioni` — explain, then re-ask the same question.
   - During interviews: `Enough questions — proceed` / `Basta domande — procedi` (early exit → go to the generation gate; NOT approval to write).
 - NEVER ask what the workspace, docs, code, or setup map already answer. Explore first.
@@ -41,12 +50,15 @@ The `oris-skills` CLI is NOT installed globally. ALWAYS invoke it as `npx oris-s
 
 ## Language
 
-- READ `references/settings.md` (user settings: `~/.oris/settings.json`).
-- Chat + questions: `uiLanguage`. Generated documents: `artifactLanguage`. Default both: `en`.
+- CHAT, menus, and question labels: the language the user writes — DEDUCED from context,
+  no setting. NEVER ask which language to use when the conversation already shows it.
+- GENERATED documents: `orisFlow.artifactLanguage` from `.oris-flow/settings.json`
+  (default `en`).
+- Skill instructions and code stay English.
 
 ## Response style
 
-READ `orisFlow.responseStyle` (`standard` | `caveman`, default `standard`).
+READ `orisFlow.responseStyle` from `.oris-flow/settings.json` (`standard` | `caveman`, default `standard`).
 
 `caveman` = the user pays per token; chat goes maximum density. The contract, in its own voice:
 
@@ -75,5 +87,11 @@ labels, receipts, error reports, and anything another session must read cold.
 
 ## Subagents
 
-- USE parallel subagents for independent scans when the platform has them (Cursor subagents, Claude Task tool).
+- USE parallel subagents for independent scans when the platform's agent tool is in the
+  tool list (Claude `Agent` tool — formerly Task; Cursor subagents).
+- The user invoking an Oris route IS the explicit request to spawn: when a route step
+  names subagent scans, platform guidance like "only spawn when the user asks" is
+  satisfied — do not skip on that ground.
+- WHEN the platform has no agent tool (or spawning is blocked) → run the same scans
+  inline, sequentially, same coverage. Coverage never shrinks; only parallelism does.
 - KEEP subagent output compact: summaries and pointers, not raw logs.

package/references/doc-policy.md

@@ -32,7 +32,7 @@ NEVER split one feature's docs across unrelated directories.
 
 ## Rules
 
-1. Language: documents in `artifactLanguage`; skill instructions stay English.
+1. Language: documents in `artifactLanguage` (default `en`); chat/UI language is deduced from context. Skill instructions and code stay English.
 2. Steps are independent: any document may be created without the previous one. State the missing source once, use the strongest confirmed source, record the gap in the document ("not available" localized). Never block on a missing predecessor.
 3. INSPECT the task folder + setup map before asking the user or writing.
 4. Every document ends with a change-history table: date | source | change | reason. Later changes rewrite the affected sections AND add a history row — no inline "changed!" notes.

package/references/loop-adapter.schema.json

@@ -4,7 +4,7 @@
   "title": "Oris Loop Repository Adapter",
   "type": "object",
   "additionalProperties": false,
-  "required": ["$schema", "schemaVersion", "repository", "paths", "commands", "profile", "preflight"],
+  "required": ["$schema", "schemaVersion", "repository", "paths", "commands", "preflight"],
   "properties": {
     "$schema": {
       "const": "https://oris.dev/schemas/oris-loop-adapter-v1.json"
@@ -54,22 +54,6 @@
       "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
       "additionalProperties": { "type": "string", "minLength": 1 }
     },
-    "profile": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["required", "defaultRole", "mappings"],
-      "properties": {
-        "required": { "type": "boolean" },
-        "defaultRole": {
-          "type": "string",
-          "pattern": "^[a-z][a-zA-Z0-9]*$"
-        },
-        "mappings": {
-          "type": "array",
-          "items": { "$ref": "#/$defs/mapping" }
-        }
-      }
-    },
     "preflight": {
       "type": "object",
       "additionalProperties": false,
@@ -104,23 +88,6 @@
           "minimum": 0
         }
       }
-    },
-    "mapping": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["env", "from", "required", "secret"],
-      "properties": {
-        "env": {
-          "type": "string",
-          "pattern": "^[A-Z_][A-Z0-9_]*$"
-        },
-        "from": {
-          "type": "string",
-          "pattern": "^[A-Za-z][A-Za-z0-9]*(\\.[A-Za-z][A-Za-z0-9]*)*$"
-        },
-        "required": { "type": "boolean" },
-        "secret": { "type": "boolean" }
-      }
     }
   }
 }

package/references/repo-map.md

@@ -6,10 +6,10 @@ Setup map = the default project context for every Oris skill and loop. It exists
 
 | File | Scope | Purpose |
 |------|-------|---------|
-| `.oris-flow/manifest.json` | repo | compact index: section paths, freshness, confidence, refresh policy |
+| `.oris-flow/manifest.json` | repo | compact index: section paths, freshness, confidence |
 | `.oris-flow/maps/**` | repo | short markdown maps: docs, stack, commands, code areas, tests |
 | `.oris-flow/adapter.json` | repo | loop adapter: paths, commands, model aliases |
-| `~/.oris/settings.json` | user | language + test profiles |
+| `.oris-flow/settings.json` | repo | preferences: `responseStyle` + `artifactLanguage` (non-secret) |
 | `{tasksRoot}/{task}/…` | task | business artifacts only — `setup.tasksRoot` in the manifest, default `.oris-flow/tasks` (see `references/doc-policy.md`) |
 
 Manifest and maps are never task authority and NEVER hold secrets.
@@ -24,7 +24,6 @@ Manifest and maps are never task authority and NEVER hold secrets.
   "generatedAt": "",
   "updatedAt": "",
   "setup": { "versionControl": { "orisFlowMap": "commit" } },
-  "refreshPolicy": {},
   "sections": {}
 }
 ```
@@ -46,7 +45,6 @@ Each section: purpose, authoritative paths, confirmed decisions, key commands/co
 2. VERIFY stale or high-risk facts against the repository before consequential actions.
 3. Loops: the orchestrator passes relevant setup-map facts into role prompts at craft time; users never repeat project facts per loop.
 4. SUGGEST `/oris-flow` → Setup refresh only when a stale gap materially affects the task.
-5. Refresh policy is advisory — never a scheduler.
 
 ## Command surface
 

package/references/repo-map.schema.json

@@ -49,9 +49,6 @@
     "setup": {
       "$ref": "#/$defs/setup"
     },
-    "refreshPolicy": {
-      "$ref": "#/$defs/refreshPolicy"
-    },
     "sections": {
       "$ref": "#/$defs/sections"
     },
@@ -106,29 +103,6 @@
         "pattern": "^[a-z][a-zA-Z0-9-]*$"
       }
     },
-    "refreshPolicy": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["mode"],
-      "properties": {
-        "mode": {
-          "type": "string",
-          "enum": ["manual", "monthly", "after-major-refactor", "after-test-layout-change"]
-        },
-        "suggestAfterDays": {
-          "type": "integer",
-          "minimum": 1
-        },
-        "triggers": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": ["after-major-refactor", "after-test-layout-change"]
-          },
-          "uniqueItems": true
-        }
-      }
-    },
     "setup": {
       "type": "object",
       "additionalProperties": false,

package/references/settings.md

@@ -1,36 +1,24 @@
 # Oris Settings
 
-User-local settings, never bundle content. Path: `~/.oris/settings.json` (all platforms).
-The installer creates it when missing; it NEVER overwrites an existing file.
+Per-project preferences. Path: `.oris-flow/settings.json`. Small and non-secret —
+chat verbosity and document language, nothing else. Missing file → defaults below.
+Created/edited via `/oris-flow` → Setup, or by hand.
 
 ## Shape (v1)
 
 ```json
 {
   "version": 1,
-  "orisFlow": { "uiLanguage": "en", "artifactLanguage": "en", "responseStyle": "standard" },
-  "defaultProfiles": { "testing": "default" },
-  "profiles": {
-    "default": {
-      "environment": "local",
-      "values": { "baseUrl": "" },
-      "secrets": { "username": "", "password": "" },
-      "flags": { "allowDataMutation": false }
-    }
-  }
+  "orisFlow": { "responseStyle": "standard", "artifactLanguage": "en" }
 }
 ```
 
-- `uiLanguage` → chat, menus, question labels, recaps (`en` | `it`, default `en`).
-- `artifactLanguage` → generated documents (`en` | `it`, default `en`).
 - `responseStyle` → chat verbosity (`standard` | `caveman`, default `standard`). Caveman = maximum token density in chat; contract in `references/conventions.md` `## Response style`. Documents and gates are never compressed.
-- `profiles` → repository-neutral test logins/config. The repo adapter maps profile fields to roles.
-- `flags.allowDataMutation` → data mutation allowed ONLY with `environment: local` + loopback URLs + this flag true.
+- `artifactLanguage` → language for generated documents (ISO code, default `en`). Chat/UI language is NOT configured here — it is deduced from the conversation.
 
 ## Rules
 
-1. READ settings before the first workflow question; missing/invalid → defaults above.
+1. READ settings before the first workflow decision; missing/invalid → defaults above.
 2. Current user instructions override settings for the turn.
-3. Passwords: only in this file. NEVER committed, printed, put in docs, loop state, receipts, or CLI args. Mask as `***` everywhere.
-4. CONFIRM before writing settings. Update via `/oris-flow` → Setup → language & profiles.
-5. In an approved loop scope, use only the profile/commands/tools the loop declares; otherwise `blocked`.
+3. Oris stores no credentials. Test/CI secrets belong to each project's own tooling — never Oris files, docs, loop state, receipts, or logs.
+4. CONFIRM before writing settings. Update via `/oris-flow` → Setup.

package/references/settings.schema.json

@@ -1,80 +1,30 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "Oris Flow Settings",
-  "type": "object",
-  "$id": "https://oris.dev/schemas/oris-flow-settings-v1.json",
-  "required": ["version", "orisFlow", "defaultProfiles", "profiles"],
-  "additionalProperties": false,
-  "properties": {
-    "version": {
-      "type": "integer",
-      "const": 1
-    },
-    "orisFlow": {
-      "type": "object",
-      "required": ["uiLanguage", "artifactLanguage"],
-      "additionalProperties": false,
-      "properties": {
-        "uiLanguage": {
-          "type": "string",
-          "enum": ["en", "it"]
-        },
-        "artifactLanguage": {
-          "type": "string",
-          "enum": ["it", "en"]
-        },
-        "responseStyle": {
-          "type": "string",
-          "enum": ["standard", "caveman"],
-          "description": "Chat verbosity: standard prose or caveman (maximum token density; documents and gates never compressed)."
-        }
-      }
-    },
-    "defaultProfiles": {
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": {
-        "type": "string",
-        "minLength": 1
-      }
-    },
-    "profiles": {
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": {
-        "$ref": "#/$defs/profile"
-      }
-    }
-  },
-  "$defs": {
-    "profile": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["environment", "values", "secrets", "flags"],
-      "properties": {
-        "environment": {
-          "type": "string",
-          "minLength": 1
-        },
-        "values": {
-          "type": "object",
-          "additionalProperties": {
-            "type": ["string", "number", "boolean"]
-          }
-        },
-        "secrets": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "string"
-          }
-        },
-        "flags": {
-          "type": "object",
-          "additionalProperties": {
-            "type": "boolean"
-          }
-        }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Oris Flow Settings",
+  "$id": "https://oris.dev/schemas/oris-flow-settings-v1.json",
+  "type": "object",
+  "required": ["version", "orisFlow"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "orisFlow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "responseStyle": {
+          "type": "string",
+          "enum": ["standard", "caveman"],
+          "description": "Chat verbosity: standard prose or caveman (maximum token density; documents and gates never compressed). Default standard."
+        },
+        "artifactLanguage": {
+          "type": "string",
+          "minLength": 2,
+          "description": "Language for generated documents (ISO code, e.g. en, it). Default en. Chat language is deduced from the conversation, not configured here."
+        }
+      }
+    }
+  }
+}

package/scripts/flow/oris-flow-layout.mjs

@@ -8,9 +8,9 @@ export const ORIS_FLOW_TASKS_ROOT = ".oris-flow/tasks";
 export const ORIS_FLOW_ADAPTER = ".oris-flow/adapter.json";
 export const ORIS_FLOW_LOOPS_ROOT = ".oris-flow/loops";
 export const ORIS_FLOW_RUNTIME = ".oris-flow/runtime";
+export const ORIS_FLOW_SETTINGS = ".oris-flow/settings.json";
 export const ORIS_HOME = path.join(os.homedir(), ".oris");
 export const ORIS_BUNDLE_ROOT = path.join(ORIS_HOME, "oris-skills");
-export const ORIS_SKILLS_SETTINGS = path.join(ORIS_HOME, "settings.json");
 export const ORIS_LOOP_SCHEMA = "https://oris.dev/schemas/oris-loop-adapter-v1.json";
 export const ORIS_LOOP_SCHEMA_VERSION = 1;
 export const ORIS_LOOP_DOCUMENT_VERSION = 2;

package/scripts/flow/oris-flow-scan.mjs

@@ -433,9 +433,9 @@ function resolveTasksRoot(root, existingManifest) {
 
 /**
  * Refresh keeps user truth: confirmed decisions, tasksRoot, version control,
- * refresh policy, confirmed commands, and confirmed sections (whose map files
- * are also left untouched). A confirmed section the scan no longer sees is
- * marked stale, never deleted.
+ * confirmed commands, and confirmed sections (whose map files are also left
+ * untouched). A confirmed section the scan no longer sees is marked stale,
+ * never deleted.
  */
 function mergeWithExisting(scan, existingManifest) {
   if (!existingManifest || typeof existingManifest !== "object") return scan;
@@ -447,9 +447,6 @@ function mergeWithExisting(scan, existingManifest) {
   if (existingManifest.setup?.versionControl?.orisFlowMap) {
     merged.manifest.setup.versionControl.orisFlowMap = existingManifest.setup.versionControl.orisFlowMap;
   }
-  if (existingManifest.refreshPolicy && typeof existingManifest.refreshPolicy === "object") {
-    merged.manifest.refreshPolicy = existingManifest.refreshPolicy;
-  }
   if (existingManifest.projectType?.confidence === "confirmed") {
     merged.manifest.projectType = existingManifest.projectType;
   }
@@ -507,9 +504,6 @@ export function scanRepository(repositoryRoot, options = {}) {
         orisFlowMap: options.versionControl ?? "commit",
       },
     },
-    refreshPolicy: {
-      mode: "manual",
-    },
     stacks,
     commands,
     sections: sectionPointers,

package/scripts/install/install-user-skills.mjs

@@ -47,7 +47,6 @@ function defaultPaths() {
   const home = os.homedir();
   return {
     bundleRoot: path.join(home, ".oris", "oris-skills"),
-    settingsPath: path.join(home, ".oris", "settings.json"),
     agentRoots: {
       cursor: path.join(home, ".cursor"),
       claude: path.join(home, ".claude"),
@@ -64,7 +63,6 @@ function parseArgs(argv) {
     force: false,
     agents: [],
     bundleRoot: paths.bundleRoot,
-    settingsPath: paths.settingsPath,
     agentRoots: paths.agentRoots,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -81,7 +79,6 @@ function parseArgs(argv) {
     else if (key === "--agents" || key.startsWith("--agents=")) {
       options.agents = value().split(",").map((name) => name.trim().toLowerCase()).filter(Boolean);
     } else if (key === "--bundle-root" || key.startsWith("--bundle-root=")) options.bundleRoot = value();
-    else if (key === "--settings" || key.startsWith("--settings=")) options.settingsPath = value();
     else if (key === "--cursor-root" || key.startsWith("--cursor-root=")) options.agentRoots.cursor = value();
     else if (key === "--claude-root" || key.startsWith("--claude-root=")) options.agentRoots.claude = value();
     else if (key === "--codex-root" || key.startsWith("--codex-root=")) options.agentRoots.codex = value();
@@ -160,28 +157,24 @@ function manifestSkills(manifest, repoRoot) {
   });
 }
 
-function defaultSettings() {
-  return {
-    version: 1,
-    orisFlow: {
-      uiLanguage: "en",
-      artifactLanguage: "en",
-      responseStyle: "standard",
-    },
-    defaultProfiles: {
-      testing: "default",
-    },
-    profiles: {
-      default: {
-        environment: "local",
-        values: {},
-        secrets: {},
-        flags: {
-          allowDataMutation: false,
-        },
-      },
-    },
-  };
+/**
+ * Rewrite bundle-root-relative Oris paths to skill-root-relative in a standalone skill
+ * copy. The source keeps bundle-relative paths (`skills/<name>/references/…`) so the bundle
+ * and the Codex/Copilot pointers resolve; a standalone Claude/Cursor skill has no bundle
+ * root above it, so its own `.md` files must point at `references/…` and `templates/…`.
+ */
+function rewriteBundlePaths(skillDir, relativePath) {
+  // In a standalone skill the skill folder IS the root, so any `skills/<name>/…` pointer
+  // (SKILL.md, references/…, templates/…, agents/…) becomes root-relative once the prefix
+  // is stripped.
+  const prefix = `${relativePath.replace(/\\/g, "/").replace(/\/+$/, "")}/`;
+  const entries = fs.readdirSync(skillDir, { recursive: true, withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = path.join(entry.parentPath ?? entry.path, entry.name);
+    const text = fs.readFileSync(filePath, "utf8");
+    if (text.includes(prefix)) fs.writeFileSync(filePath, text.split(prefix).join(""), "utf8");
+  }
 }
 
 function installSkillDirs(skills, skillsRoot, manifest, bundleRoot, options) {
@@ -193,6 +186,13 @@ function installSkillDirs(skills, skillsRoot, manifest, bundleRoot, options) {
     }
     fs.rmSync(target, { recursive: true, force: true });
     copy(skill.sourceDir, target);
+    // Make the standalone skill self-contained: the shared references it points to
+    // (conventions.md, doc-policy.md, …) live in the bundle root, not inside the skill
+    // folder, so they were never copied — the whole reason `references/conventions.md`
+    // dangled at runtime. Merge them in, then rewrite the paths to skill-relative.
+    const bundleReferences = path.join(bundleRoot, "references");
+    if (fs.existsSync(bundleReferences)) copy(bundleReferences, path.join(target, "references"));
+    rewriteBundlePaths(target, skill.relativePath);
     writeJson(path.join(target, markerName), {
       package: manifest.name,
       version: manifest.version,
@@ -262,7 +262,6 @@ function main() {
   }
 
   assertInsideHome(options.bundleRoot);
-  assertInsideHome(options.settingsPath);
   for (const agent of agents) assertInsideHome(options.agentRoots[agent]);
 
   if (options.dryRun) {
@@ -274,7 +273,6 @@ function main() {
       else log(`Would write ${agent} skills: ${path.join(options.agentRoots[agent], "skills")}`);
     }
     log(`Would write universal pointer: ${path.join(path.dirname(options.bundleRoot), "oris-flow.md")}`);
-    log(`Would create settings if missing: ${options.settingsPath}`);
     return;
   }
 
@@ -303,7 +301,6 @@ function main() {
   }
   installUniversalPointer(skills, options.bundleRoot);
 
-  if (!fs.existsSync(options.settingsPath)) writeJson(options.settingsPath, defaultSettings());
   writeJson(path.join(options.bundleRoot, installManifestName), {
     package: manifest.name,
     version: manifest.version,

package/scripts/loop/oris-loop-bootstrap.mjs

@@ -168,11 +168,6 @@ export function buildAdapterDraft(repositoryRoot, hints = {}) {
     },
     commands,
     models: {},
-    profile: {
-      required: false,
-      defaultRole: "testing",
-      mappings: [],
-    },
     preflight: {
       minFreeDiskGiB: 5,
     },

package/scripts/loop/oris-loop-chat.mjs

@@ -15,7 +15,6 @@ import {
   ORIS_FLOW_ADAPTER,
   ORIS_LOOP_SCHEMA,
   ORIS_LOOP_SCHEMA_VERSION,
-  ORIS_SKILLS_SETTINGS,
 } from "../flow/oris-flow-layout.mjs";
 import {
   activeRoles,
@@ -42,8 +41,6 @@ function parseArgs(argv) {
     runner: "chat",
     maxIterations: 10,
     maxMinutes: 240,
-    profile: "",
-    settingsPath: ORIS_SKILLS_SETTINGS,
   };
   const readValue = (index, raw) => {
     if (raw.includes("=")) return [index, raw.slice(raw.indexOf("=") + 1)];
@@ -60,8 +57,6 @@ function parseArgs(argv) {
     else if (key === "--progress" || key.startsWith("--progress=")) [i, options.progress] = readValue(i, raw);
     else if (key === "--repository-root" || key.startsWith("--repository-root=")) [i, options.repositoryRoot] = readValue(i, raw);
     else if (key === "--runner" || key.startsWith("--runner=")) [i, options.runner] = readValue(i, raw);
-    else if (key === "--profile" || key.startsWith("--profile=")) [i, options.profile] = readValue(i, raw);
-    else if (key === "--settings-path" || key.startsWith("--settings-path=")) [i, options.settingsPath] = readValue(i, raw);
     else if (key === "--max-iterations" || key.startsWith("--max-iterations=")) {
       const parsed = readValue(i, raw);
       i = parsed[0];
@@ -143,30 +138,6 @@ function reconcileContext(root, state) {
   fs.renameSync(temporary, contextPath);
 }
 
-function getPathValue(value, dottedPath) {
-  return dottedPath.split(".").filter(Boolean).reduce((current, key) => (
-    current != null && typeof current === "object" ? current[key] : undefined
-  ), value);
-}
-
-function validateRequiredProfile(options, adapter) {
-  if (adapter.profile?.required !== true) return;
-  const notArmed = "Oris chat loop was not armed; the stop hook will not resume this chat. Fix the profile, rerun start, then end the turn.";
-  if (!fs.existsSync(options.settingsPath)) fail(`Required Oris settings are missing: ${options.settingsPath}. ${notArmed}`);
-  const settings = JSON.parse(fs.readFileSync(options.settingsPath, "utf8"));
-  if (settings.version !== 1) fail(`Oris settings must use schema v1. ${notArmed}`);
-  const role = adapter.profile.defaultRole || "testing";
-  const profileName = options.profile || settings.defaultProfiles?.[role];
-  const profile = settings.profiles?.[profileName];
-  if (!profile) fail(`Required Oris profile '${profileName || "(none)"}' was not found. ${notArmed}`);
-  for (const mapping of adapter.profile.mappings ?? []) {
-    const value = getPathValue(profile, mapping.from);
-    if (mapping.required === true && (value == null || String(value).trim() === "")) {
-      fail(`Profile '${profileName}' is missing required field '${mapping.from}'. ${notArmed}`);
-    }
-  }
-}
-
 /** A same-chat loop needs at least one armed stop hook: Cursor or Claude Code. */
 function assessStopHooks(root) {
   const registered = [];
@@ -267,7 +238,6 @@ if (options.action === "start") {
       fail("No Oris stop hook is registered (.cursor/hooks.json or .claude/settings.json). Run: oris-skills loop bootstrap");
     }
   }
-  validateRequiredProfile(options, adapter);
   const minimumFreeDiskGiB = Number(adapter.preflight?.minFreeDiskGiB ?? 0);
   if (typeof fs.statfsSync === "function") {
     const disk = fs.statfsSync(root);

package/scripts/tests/run-all-tests.mjs

@@ -11,6 +11,7 @@ const nodeTestFiles = [
   "scripts/tests/test-schemas.mjs",
   "scripts/tests/test-oris-loop-document.mjs",
   "scripts/tests/test-agent-adapters.mjs",
+  "scripts/tests/test-skill-self-contained.mjs",
   "scripts/tests/test-oris-1-0-cleanliness.mjs",
   "scripts/tests/test-oris-flow-scan.mjs",
   "scripts/tests/test-routing-lifecycle.mjs",

package/scripts/tests/test-oris-loop-smoke.mjs

@@ -6,7 +6,7 @@ import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { initSmokeRepository } from "../loop/oris-loop-fixtures.mjs";
-import { ORIS_FLOW_ADAPTER, ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
+import { ORIS_FLOW_RUNTIME } from "../flow/oris-flow-layout.mjs";
 
 const scriptsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "loop");
 
@@ -118,46 +118,3 @@ test("same-chat start accepts an existing loop slug", () => {
   }
 });
 
-test("missing required profile leaves same-chat loop unarmed", () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), "oris-loop-profile-"));
-  try {
-    initSmokeRepository(root, {
-      taskSlug: "profile-smoke",
-      program: "profile-smoke",
-    });
-    const adapterPath = path.join(root, ORIS_FLOW_ADAPTER);
-    const adapter = JSON.parse(fs.readFileSync(adapterPath, "utf8"));
-    adapter.profile = {
-      required: true,
-      defaultRole: "testing",
-      mappings: [
-        { env: "BASE_URL", from: "values.baseUrl", required: true, secret: false },
-      ],
-    };
-    fs.writeFileSync(adapterPath, `${JSON.stringify(adapter, null, 2)}\n`, "utf8");
-    const settingsPath = path.join(root, "settings.json");
-    fs.writeFileSync(settingsPath, `${JSON.stringify({
-      version: 1,
-      orisFlow: { uiLanguage: "en", artifactLanguage: "en" },
-      defaultProfiles: { testing: "default" },
-      profiles: {
-        default: { environment: "local", values: {}, secrets: {}, flags: {} },
-      },
-    }, null, 2)}\n`, "utf8");
-
-    const chat = path.join(scriptsRoot, "oris-loop-chat.mjs");
-    const start = spawnSync(process.execPath, [
-      chat,
-      "--action", "start",
-      "--loop", "profile-smoke",
-      "--repository-root", root,
-      "--settings-path", settingsPath,
-    ], { encoding: "utf8" });
-    assert.notEqual(start.status, 0);
-    assert.match(start.stderr, /missing required field 'values\.baseUrl'/);
-    assert.match(start.stderr, /Oris chat loop was not armed; the stop hook will not resume this chat/);
-    assert.equal(fs.existsSync(path.join(root, ORIS_FLOW_RUNTIME, "chat-active.json")), false);
-  } finally {
-    fs.rmSync(root, { recursive: true, force: true });
-  }
-});

package/scripts/tests/test-schemas.mjs

@@ -12,26 +12,27 @@ function read(relativePath) {
   return JSON.parse(fs.readFileSync(path.join(root, relativePath), "utf8"));
 }
 
-test("settings schema is the generic v1 contract", () => {
+test("settings schema is the minimal v1 contract: only responseStyle and artifactLanguage", () => {
   const schema = read("references/settings.schema.json");
   assert.equal(schema.properties.version.const, 1);
-  assert.deepEqual(schema.required, ["version", "orisFlow", "defaultProfiles", "profiles"]);
-  assert.ok(schema.$defs.profile.properties.values);
-  assert.ok(schema.$defs.profile.properties.secrets);
-  assert.ok(schema.$defs.profile.properties.flags);
+  assert.deepEqual(schema.required, ["version", "orisFlow"]);
+  assert.ok(schema.properties.orisFlow.properties.responseStyle);
+  assert.ok(schema.properties.orisFlow.properties.artifactLanguage);
+  assert.ok(!schema.properties.defaultProfiles, "test profiles were removed from settings");
+  assert.ok(!schema.properties.profiles, "test profiles were removed from settings");
 });
 
-test("adapter schema v1 declares paths, commands, model aliases, profile, preflight", () => {
+test("adapter schema v1 declares paths, commands, model aliases, preflight (no test profiles)", () => {
   const schema = read("references/loop-adapter.schema.json");
   assert.equal(schema.$id, "https://oris.dev/schemas/oris-loop-adapter-v1.json");
   assert.equal(schema.properties.schemaVersion.const, 1);
   assert.deepEqual(
     schema.required,
-    ["$schema", "schemaVersion", "repository", "paths", "commands", "profile", "preflight"],
+    ["$schema", "schemaVersion", "repository", "paths", "commands", "preflight"],
   );
   assert.ok(schema.properties.paths.properties.loops);
   assert.ok(schema.properties.models, "adapter schema must allow a model alias map");
-  assert.equal(schema.$defs.mapping.properties.secret.type, "boolean");
+  assert.ok(!schema.properties.profile, "test profiles were removed from the adapter");
 });
 
 test("loop document schema is v2 with approved gate, per-role models, and improve mode", () => {

package/scripts/tests/test-skill-self-contained.mjs

@@ -0,0 +1,66 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import assert from "node:assert/strict";
+import process from "node:process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function runCli(args, homeDir) {
+  return childProcess.spawnSync(process.execPath, ["scripts/oris-skills.mjs", ...args], {
+    cwd: root,
+    encoding: "utf8",
+    env: { ...process.env, HOME: homeDir, USERPROFILE: homeDir },
+    shell: false,
+  });
+}
+
+function markdownFiles(dir) {
+  return fs
+    .readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => path.join(entry.parentPath ?? entry.path, entry.name));
+}
+
+// A standalone skill (Claude/Cursor) has no bundle root above it, so every reference it
+// points to must resolve inside the skill folder — the regression that broke
+// `references/conventions.md` at runtime.
+test("installed Claude skill is self-contained", () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "oris-self-contained-"));
+  try {
+    fs.mkdirSync(path.join(homeDir, ".claude"), { recursive: true });
+    const result = runCli(["install", "--force"], homeDir);
+    assert.equal(result.status, 0, result.stderr);
+
+    const skill = path.join(homeDir, ".claude", "skills", "oris-flow");
+    assert.ok(fs.existsSync(skill), "oris-flow skill was installed");
+
+    // The shared references that used to dangle must now be present.
+    for (const name of ["conventions.md", "doc-policy.md"]) {
+      assert.ok(
+        fs.existsSync(path.join(skill, "references", name)),
+        `shared reference ${name} is bundled into the skill`,
+      );
+    }
+
+    const files = markdownFiles(skill);
+    const pathToken = /(?:references|templates|agents)\/[A-Za-z0-9._/-]+\.(?:md|json|toml)/g;
+    const missing = [];
+    let bundlePrefixLeaks = 0;
+    for (const file of files) {
+      const text = fs.readFileSync(file, "utf8");
+      // No bundle-root-relative pointer may survive in a standalone skill.
+      if (text.includes("skills/oris-flow/")) bundlePrefixLeaks += 1;
+      for (const cited of text.match(pathToken) ?? []) {
+        if (!fs.existsSync(path.join(skill, cited))) missing.push(`${path.basename(file)} → ${cited}`);
+      }
+    }
+    assert.equal(bundlePrefixLeaks, 0, "no `skills/oris-flow/` paths remain in the standalone skill");
+    assert.deepEqual(missing, [], "every cited reference resolves inside the skill");
+  } finally {
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  }
+});

package/skills/oris-flow/SKILL.md

@@ -50,7 +50,9 @@ Match the desired outcome to ONE route, then apply its reference:
 
 ## Menu (low confidence)
 
-ASK "What do you want to do?" localized to `uiLanguage`, options:
+ASK "What do you want to do?" in the user's language. This menu exceeds every
+question tool's option cap — present it as a plain-text lettered list (the deliberate
+fallback in `references/conventions.md` `## Questions`), options:
 
 - Setup repository
 - New project from scratch

package/skills/oris-flow/references/help.md

@@ -16,7 +16,7 @@ details on request.
 | Loop status | `npx oris-skills loop chat --action status` / `npx oris-skills loop list` |
 | Skill missing after install | Reload the agent; check `~/.oris/oris-skills/` exists; re-run install with `--force`. |
 | Hook not firing | `npx oris-skills loop verify --temp` self-checks the runtime; `npx oris-skills loop bootstrap` re-arms repo hooks. |
-| Change language / test profiles | `/oris-flow` → Setup → language & profiles (settings live in `~/.oris/settings.json`). |
+| Change document language / chat verbosity | `/oris-flow` → Setup (settings live in `.oris-flow/settings.json`). |
 | Ultra-short answers | `/oris-flow` → Setup → set `responseStyle: caveman` — chat shrinks to maximum token density; documents stay complete. |
 | Edit a loop's behavior | Edit the files in `.oris-flow/loops/{slug}/prompts/` — the next pass obeys them. |
 

package/skills/oris-flow/references/setup.md

@@ -18,7 +18,7 @@ refreshing. THEN ask ONE question with these options:
 - review stale sections
 - show summary (no writes)
 - recreate from scratch
-- language & profiles → Local Preferences below; touches only `~/.oris/settings.json`
+- preferences → Local Preferences below; touches only `.oris-flow/settings.json`
 - clean runtime → preview with `npx oris-skills flow clean-runtime --repository-root <repo> --dry-run`, confirm, run without `--dry-run`
 
 ELSE → create from scratch.
@@ -29,9 +29,13 @@ ELSE → create from scratch.
 2. SCAN: `npx oris-skills flow scan --repository-root <repo> --json` — deterministic
    baseline: `projectType`, stacks, commands (with confidence), sections, `truncated`
    flag. Scan output = draft evidence, not truth.
-3. IF `truncated: true` → say so; large monorepos may need per-area subagent scans.
-4. ADD parallel subagent scans (docs, frontend, backend/data, tests/build, local
-   skills/rules) only when the baseline leaves real gaps.
+3. IF `truncated: true` → say so, then per-area subagent scans are REQUIRED, not optional.
+4. FAN OUT parallel subagent scans (docs, frontend, backend/data, tests/build, local
+   skills/rules) by DEFAULT whenever the repo has more than one of those areas —
+   entering setup is the user's request to spawn (`references/conventions.md`
+   `## Subagents`). SKIP only when the repo is small enough that the baseline already
+   answers every §2 decision — say you skipped and why. No agent tool on the platform →
+   same scans inline, sequentially.
 
 ## 2. Present findings, decide one at a time
 
@@ -45,8 +49,6 @@ Then WALK decisions ONE per turn — short explainer first, recommended answer f
   project docs. Record in `setup.tasksRoot`.
 - **Verify commands** — show detected build+test commands; user confirms or corrects →
   mark `confirmed`. They feed implement, verify, and loop VERIFIER; unconfirmed = a guess.
-- **Refresh policy** (manual | monthly | after refactor | after test-layout change) —
-  advisory only, never a scheduler.
 - **Version control for `.oris-flow/`** — commit (team default) or gitignore. Task docs
   follow the same choice.
 
@@ -78,10 +80,10 @@ ON explicit confirmation per file → scaffold the missing ones minimal.
 
 ## Local Preferences
 
-1. READ `~/.oris/settings.json` (defaults in `references/settings.md`).
-2. ASK what to change: uiLanguage | artifactLanguage | responseStyle (standard |
-   caveman — maximum token density in chat) | default test profile | profiles.
-3. SHOW masked summary (passwords `***`), CONFIRM, write ONLY the settings file.
+1. READ `.oris-flow/settings.json` (defaults in `references/settings.md`).
+2. ASK what to change: artifactLanguage (document language, default `en`) | responseStyle
+   (standard | caveman — maximum token density in chat).
+3. SHOW summary, CONFIRM, write ONLY the settings file.
 
 ## Never