oris-skills 2.0.0

package/references/settings.md

@@ -0,0 +1,35 @@
+# 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.
+
+## Shape (v1)
+
+```json
+{
+  "version": 1,
+  "orisFlow": { "uiLanguage": "en", "artifactLanguage": "en" },
+  "defaultProfiles": { "testing": "default" },
+  "profiles": {
+    "default": {
+      "environment": "local",
+      "values": { "baseUrl": "" },
+      "secrets": { "username": "", "password": "" },
+      "flags": { "allowDataMutation": false }
+    }
+  }
+}
+```
+
+- `uiLanguage` → chat, menus, question labels, recaps (`en` | `it`, default `en`).
+- `artifactLanguage` → generated documents (`en` | `it`, default `en`).
+- `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.
+
+## Rules
+
+1. READ settings before the first workflow question; 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`.

package/references/settings.schema.json

@@ -0,0 +1,75 @@
+{
+  "$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"]
+        }
+      }
+    },
+    "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"
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/flow/oris-flow-clean-runtime.mjs

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  ORIS_FLOW_ADAPTER,
+  ORIS_FLOW_LOOPS_ROOT,
+  ORIS_FLOW_MANIFEST,
+  ORIS_FLOW_MAPS_ROOT,
+  ORIS_FLOW_RUNTIME,
+} from "./oris-flow-layout.mjs";
+
+const DEFAULT_RUNTIME_RELATIVE = ORIS_FLOW_RUNTIME;
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function assertSafeRelativePath(relativePath, label) {
+  const normalized = String(relativePath ?? "").replace(/\\/g, "/");
+  if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`${label} must be a repository-relative path.`);
+  }
+  if (normalized.split("/").includes("..")) {
+    throw new Error(`${label} must not contain '..'.`);
+  }
+  return normalized;
+}
+
+function assertUnderRepository(repositoryRoot, targetPath) {
+  const root = path.resolve(repositoryRoot);
+  const resolved = path.resolve(targetPath);
+  const relative = path.relative(root, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Refusing to clean path outside repository: ${targetPath}`);
+  }
+  return resolved;
+}
+
+export function resolveCleanTargets(repositoryRoot) {
+  const root = path.resolve(repositoryRoot);
+  const adapter = readJson(path.join(root, ORIS_FLOW_ADAPTER));
+  const runtimeRelative = assertSafeRelativePath(
+    adapter?.paths?.runtime ?? DEFAULT_RUNTIME_RELATIVE,
+    "paths.runtime",
+  );
+
+  if (runtimeRelative.replace(/\\/g, "/") === ORIS_FLOW_RUNTIME) {
+    return [assertUnderRepository(root, path.join(root, ...ORIS_FLOW_RUNTIME.split("/")))];
+  }
+
+  return [assertUnderRepository(root, path.join(root, ...runtimeRelative.split("/")))];
+}
+
+function listEntries(directoryPath) {
+  if (!fs.existsSync(directoryPath)) return [];
+  const entries = [];
+  const stack = [directoryPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      entries.push(fullPath);
+      if (entry.isDirectory()) stack.push(fullPath);
+    }
+  }
+  return entries.sort();
+}
+
+function removeEntry(entryPath) {
+  if (!fs.existsSync(entryPath)) return;
+  const stat = fs.lstatSync(entryPath);
+  if (stat.isDirectory()) {
+    fs.rmSync(entryPath, { recursive: true, force: true });
+    return;
+  }
+  fs.rmSync(entryPath, { force: true });
+}
+
+export function cleanFlowRuntime(repositoryRoot, options = {}) {
+  const root = path.resolve(repositoryRoot);
+  const dryRun = Boolean(options.dryRun);
+  const targets = resolveCleanTargets(root);
+  const removed = [];
+  const preserved = [
+    ORIS_FLOW_MANIFEST,
+    `${ORIS_FLOW_MAPS_ROOT}/**`,
+    ORIS_FLOW_ADAPTER,
+    `${ORIS_FLOW_LOOPS_ROOT}/**`,
+    ".cursor/hooks.json",
+    ".cursor/hooks/oris-loop-stop.mjs",
+  ];
+
+  for (const target of targets) {
+    if (!fs.existsSync(target)) continue;
+    const stat = fs.lstatSync(target);
+    if (stat.isDirectory()) {
+      for (const entry of listEntries(target)) {
+        const relative = path.relative(root, entry).split(path.sep).join("/");
+        if (dryRun) {
+          removed.push(relative);
+        } else {
+          removeEntry(entry);
+          removed.push(relative);
+        }
+      }
+      if (dryRun) {
+        removed.push(path.relative(root, target).split(path.sep).join("/"));
+      } else {
+        removeEntry(target);
+        removed.push(path.relative(root, target).split(path.sep).join("/"));
+      }
+      continue;
+    }
+    const relative = path.relative(root, target).split(path.sep).join("/");
+    if (dryRun) {
+      removed.push(relative);
+    } else {
+      removeEntry(target);
+      removed.push(relative);
+    }
+  }
+
+  return {
+    repositoryRoot: root,
+    dryRun,
+    targets: targets.map((target) => path.relative(root, target).split(path.sep).join("/")),
+    removed,
+    preserved,
+    cleaned: removed.length > 0,
+  };
+}
+
+function parseArgs(argv) {
+  const options = {
+    repositoryRoot: process.cwd(),
+    dryRun: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (raw === "--dry-run") options.dryRun = true;
+    else if (raw === "--json") options.json = true;
+    else if (raw.startsWith("--repository-root=")) options.repositoryRoot = raw.slice("--repository-root=".length);
+    else if (raw === "--repository-root" && argv[i + 1]) {
+      options.repositoryRoot = argv[i + 1];
+      i += 1;
+    } else if (!raw.startsWith("-")) {
+      options.repositoryRoot = raw;
+    }
+  }
+  return options;
+}
+
+export function printCleanReport(result) {
+  console.log(`Oris Flow runtime clean${result.dryRun ? " (dry run)" : ""}`);
+  console.log(`Repository: ${result.repositoryRoot}`);
+  console.log("");
+  console.log("Targets:");
+  for (const target of result.targets) console.log(`- ${target}`);
+  console.log("");
+  if (result.removed.length === 0) {
+    console.log("No ephemeral runtime files found.");
+    return;
+  }
+  console.log(`${result.dryRun ? "Would remove" : "Removed"} ${result.removed.length} path(s):`);
+  for (const entry of result.removed) console.log(`- ${entry}`);
+  console.log("");
+  console.log("Preserved by design:");
+  for (const entry of result.preserved) console.log(`- ${entry}`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  const options = parseArgs(process.argv.slice(2));
+  const result = cleanFlowRuntime(options.repositoryRoot, { dryRun: options.dryRun });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printCleanReport(result);
+  }
+  process.exit(0);
+}

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

@@ -0,0 +1,53 @@
+import os from "node:os";
+import path from "node:path";
+
+export const ORIS_FLOW_ROOT = ".oris-flow";
+export const ORIS_FLOW_MANIFEST = ".oris-flow/manifest.json";
+export const ORIS_FLOW_MAPS_ROOT = ".oris-flow/maps";
+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_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;
+export const ORIS_FLOW_MAP_SCHEMA = "https://oris.dev/schemas/oris-flow-map-v1.json";
+export const ORIS_FLOW_MAP_SCHEMA_VERSION = 1;
+
+export function toPosixPath(value) {
+  return String(value).replace(/\\/g, "/");
+}
+
+export function safeSlug(value, fallback = "loop") {
+  const raw = path.basename(toPosixPath(value || fallback));
+  const slug = raw.replace(/[^A-Za-z0-9_.-]/g, "-").replace(/^-+|-+$/g, "");
+  return slug || fallback;
+}
+
+export function assertRepositoryRelative(value, label) {
+  const normalized = toPosixPath(value ?? "");
+  if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized)) {
+    throw new Error(`${label} must be a repository-relative path.`);
+  }
+  if (normalized.split("/").includes("..")) {
+    throw new Error(`${label} must not contain '..'.`);
+  }
+  return normalized;
+}
+
+export function resolveInsideRepository(repositoryRoot, relativePath, label = "path") {
+  const root = path.resolve(repositoryRoot);
+  const normalized = assertRepositoryRelative(relativePath, label);
+  const resolved = path.resolve(root, ...normalized.split("/"));
+  const relative = path.relative(root, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} must be below repository root: ${relativePath}`);
+  }
+  return resolved;
+}
+
+export function relativeToRepository(repositoryRoot, targetPath) {
+  return toPosixPath(path.relative(path.resolve(repositoryRoot), path.resolve(targetPath)));
+}

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

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import {
+  ORIS_FLOW_MANIFEST,
+  ORIS_FLOW_MAP_SCHEMA,
+  ORIS_FLOW_MAP_SCHEMA_VERSION,
+  ORIS_FLOW_MAPS_ROOT,
+  relativeToRepository,
+  resolveInsideRepository,
+  toPosixPath,
+} from "./oris-flow-layout.mjs";
+
+const ignoredDirectories = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "dist",
+  "build",
+  "bin",
+  "obj",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".venv",
+  "venv",
+  "__pycache__",
+]);
+
+const stackDetectors = [
+  { id: "node", label: "Node.js", match: (file) => file.name === "package.json" },
+  { id: "pnpm", label: "pnpm", match: (file) => file.name === "pnpm-lock.yaml" },
+  { id: "yarn", label: "Yarn", match: (file) => file.name === "yarn.lock" },
+  { id: "dotnet", label: ".NET", match: (file) => /\.(sln|csproj|fsproj|vbproj)$/i.test(file.name) },
+  { id: "python", label: "Python", match: (file) => ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"].includes(file.name) },
+  { id: "java", label: "Java", match: (file) => ["pom.xml", "build.gradle", "build.gradle.kts"].includes(file.name) },
+  { id: "go", label: "Go", match: (file) => file.name === "go.mod" },
+  { id: "rust", label: "Rust", match: (file) => file.name === "Cargo.toml" },
+  { id: "playwright", label: "Playwright", match: (file) => /^playwright\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
+  { id: "vitest", label: "Vitest", match: (file) => /^vitest\.config\.(ts|js|mjs|cjs)$/i.test(file.name) },
+  { id: "jest", label: "Jest", match: (file) => /^jest\.config\.(ts|js|mjs|cjs)$/i.test(file.name) || file.name === "jest.config.json" },
+  { id: "docker", label: "Docker", match: (file) => file.name === "Dockerfile" || file.name === "docker-compose.yml" || file.name === "compose.yaml" },
+  { id: "azure-pipelines", label: "Azure Pipelines", match: (file) => /^azure-pipelines.*\.ya?ml$/i.test(file.name) },
+  { id: "github-actions", label: "GitHub Actions", match: (file) => file.relative.startsWith(".github/workflows/") && /\.ya?ml$/i.test(file.name) },
+];
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const options = {
+    repositoryRoot: process.cwd(),
+    write: false,
+    json: false,
+    area: "",
+  };
+  const readValue = (index, raw) => {
+    if (raw.includes("=")) return [index, raw.slice(raw.indexOf("=") + 1)];
+    if (index + 1 >= argv.length) fail(`Missing value for ${raw}.`);
+    return [index + 1, argv[index + 1]];
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    const key = raw.toLowerCase();
+    if (key === "--repository-root" || key.startsWith("--repository-root=")) [i, options.repositoryRoot] = readValue(i, raw);
+    else if (key === "--write") options.write = true;
+    else if (key === "--json") options.json = true;
+    else if (key === "--area" || key.startsWith("--area=")) [i, options.area] = readValue(i, raw);
+    else fail(`Unknown argument: ${raw}`);
+  }
+  return options;
+}
+
+function walk(root, options = {}) {
+  const maxFiles = Number(options.maxFiles ?? 6000);
+  const files = [];
+  const stack = [root];
+  while (stack.length > 0 && files.length < maxFiles) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (ignoredDirectories.has(entry.name)) continue;
+      const full = path.join(current, entry.name);
+      const relative = relativeToRepository(root, full);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        files.push({ full, relative, name: entry.name });
+      }
+      if (files.length >= maxFiles) break;
+    }
+  }
+  return files;
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function detectStacks(files) {
+  const stacks = new Map();
+  for (const file of files) {
+    for (const detector of stackDetectors) {
+      if (!detector.match(file)) continue;
+      const current = stacks.get(detector.id) ?? { id: detector.id, label: detector.label, evidence: [] };
+      current.evidence.push(file.relative);
+      stacks.set(detector.id, current);
+    }
+  }
+  return [...stacks.values()].map((stack) => ({
+    ...stack,
+    evidence: stack.evidence.slice(0, 8),
+  }));
+}
+
+function findPackageCommands(files) {
+  const commands = [];
+  for (const file of files.filter((item) => item.name === "package.json")) {
+    const pkg = readJson(file.full);
+    const scripts = pkg?.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    const cwd = path.dirname(file.relative) === "." ? "." : toPosixPath(path.dirname(file.relative));
+    for (const name of ["check", "test", "lint", "build", "typecheck"]) {
+      if (scripts[name]) {
+        commands.push({
+          name,
+          cwd,
+          command: cwd === "." ? `npm run ${name}` : `npm run ${name} --prefix ${cwd}`,
+          evidence: file.relative,
+        });
+      }
+    }
+  }
+  return commands;
+}
+
+function hasAny(files, predicate) {
+  return files.some(predicate);
+}
+
+function makeSection(pathValue, summary, details) {
+  return {
+    pointer: {
+      path: pathValue,
+      confidence: details.confidence ?? "detected",
+      lastScannedAt: details.scannedAt,
+      stale: false,
+      summary,
+    },
+    markdown: details.markdown,
+  };
+}
+
+function buildSections(root, files, stacks, commands, scannedAt) {
+  const sections = {};
+  const topFiles = files.map((file) => file.relative);
+
+  if (hasAny(files, (file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING)\.md$/i.test(file.relative) || file.relative.startsWith("docs/"))) {
+    const docs = topFiles.filter((file) => /(^|\/)(README|CONTEXT|CHANGELOG|CONTRIBUTING)\.md$/i.test(file) || file.startsWith("docs/")).slice(0, 20);
+    sections.docs = makeSection(".oris-flow/maps/docs.md", "Documentation and task context detected.", {
+      scannedAt,
+      markdown: [
+        "# Docs",
+        "",
+        "Detected documentation paths:",
+        ...docs.map((file) => `- ${file}`),
+        "",
+      ].join("\n"),
+    });
+  }
+
+  if (hasAny(files, (file) => file.relative.startsWith(".cursor/skills/") || file.relative.startsWith(".cursor/rules/"))) {
+    const cursorFiles = topFiles.filter((file) => file.startsWith(".cursor/skills/") || file.startsWith(".cursor/rules/")).slice(0, 20);
+    sections.cursorGuidance = makeSection(".oris-flow/maps/cursor-guidance.md", "Project-local Cursor skills or rules detected.", {
+      scannedAt,
+      markdown: [
+        "# Cursor Guidance",
+        "",
+        "Detected local Cursor guidance:",
+        ...cursorFiles.map((file) => `- ${file}`),
+        "",
+      ].join("\n"),
+    });
+  }
+
+  if (stacks.length > 0) {
+    sections.stack = makeSection(".oris-flow/maps/stack.md", `Detected ${stacks.length} stack signal(s).`, {
+      scannedAt,
+      markdown: [
+        "# Stack",
+        "",
+        ...stacks.flatMap((stack) => [
+          `## ${stack.label}`,
+          "",
+          ...stack.evidence.map((file) => `- ${file}`),
+          "",
+        ]),
+      ].join("\n"),
+    });
+  }
+
+  if (commands.length > 0) {
+    sections.commands = makeSection(".oris-flow/maps/commands.md", `Detected ${commands.length} package command(s).`, {
+      scannedAt,
+      markdown: [
+        "# Commands",
+        "",
+        ...commands.map((command) => `- \`${command.command}\` (${command.evidence})`),
+        "",
+      ].join("\n"),
+    });
+  }
+
+  if (hasAny(files, (file) => /(^|\/)(src|app|apps|packages)\//.test(file.relative))) {
+    const codeRoots = [...new Set(topFiles
+      .filter((file) => /(^|\/)(src|app|apps|packages)\//.test(file))
+      .map((file) => file.split("/").slice(0, 2).join("/")))]
+      .slice(0, 20);
+    sections.code = makeSection(".oris-flow/maps/code.md", "Source code areas detected.", {
+      scannedAt,
+      markdown: [
+        "# Code",
+        "",
+        "Detected source areas:",
+        ...codeRoots.map((file) => `- ${file}`),
+        "",
+      ].join("\n"),
+    });
+  }
+
+  if (hasAny(files, (file) => /(^|\/)(test|tests|spec|specs|e2e)(\/|$)|\.(test|spec)\.[jt]sx?$/i.test(file.relative))) {
+    const tests = topFiles.filter((file) => /(^|\/)(test|tests|spec|specs|e2e)(\/|$)|\.(test|spec)\.[jt]sx?$/i.test(file)).slice(0, 20);
+    sections.tests = makeSection(".oris-flow/maps/tests.md", "Test assets detected.", {
+      scannedAt,
+      markdown: [
+        "# Tests",
+        "",
+        "Detected test paths:",
+        ...tests.map((file) => `- ${file}`),
+        "",
+      ].join("\n"),
+    });
+  }
+
+  return sections;
+}
+
+export function scanRepository(repositoryRoot, options = {}) {
+  const root = path.resolve(repositoryRoot);
+  const scannedAt = new Date().toISOString();
+  const files = walk(root, options);
+  const stacks = detectStacks(files);
+  const commands = findPackageCommands(files);
+  const sections = buildSections(root, files, stacks, commands, scannedAt);
+  const sectionPointers = Object.fromEntries(
+    Object.entries(sections).map(([key, value]) => [key, value.pointer]),
+  );
+  const manifest = {
+    $schema: ORIS_FLOW_MAP_SCHEMA,
+    schemaVersion: ORIS_FLOW_MAP_SCHEMA_VERSION,
+    repository: path.basename(root),
+    generatedAt: scannedAt,
+    updatedAt: scannedAt,
+    setup: {
+      mode: options.mode ?? "create",
+      scanDepth: options.scanDepth ?? "balanced",
+      confirmedDecisions: [],
+      versionControl: {
+        orisFlowMap: options.versionControl ?? "commit",
+      },
+    },
+    refreshPolicy: {
+      mode: "manual",
+    },
+    stacks,
+    commands,
+    sections: sectionPointers,
+  };
+  return {
+    repositoryRoot: root,
+    scannedAt,
+    fileCount: files.length,
+    stacks,
+    commands,
+    sections,
+    manifest,
+  };
+}
+
+export function writeScanResult(scan) {
+  const root = scan.repositoryRoot;
+  const manifestPath = resolveInsideRepository(root, ORIS_FLOW_MANIFEST, "Oris Flow manifest");
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(scan.manifest, null, 2)}\n`, "utf8");
+
+  for (const section of Object.values(scan.sections)) {
+    const sectionPath = resolveInsideRepository(root, section.pointer.path, "Oris Flow section");
+    fs.mkdirSync(path.dirname(sectionPath), { recursive: true });
+    fs.writeFileSync(sectionPath, section.markdown, "utf8");
+  }
+
+  const readmePath = resolveInsideRepository(root, `${ORIS_FLOW_MAPS_ROOT}/README.md`, "Oris Flow map README");
+  if (!fs.existsSync(readmePath)) {
+    fs.mkdirSync(path.dirname(readmePath), { recursive: true });
+    fs.writeFileSync(readmePath, "# Oris Flow Maps\n\nGenerated by `oris-flow-scan.mjs`. Sections are present only when repository evidence supports them.\n", "utf8");
+  }
+  return {
+    manifestPath: relativeToRepository(root, manifestPath),
+    sectionPaths: Object.values(scan.sections).map((section) => section.pointer.path),
+  };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+  const options = parseArgs(process.argv.slice(2));
+  const scan = scanRepository(options.repositoryRoot, options);
+  const written = options.write ? writeScanResult(scan) : null;
+  const payload = {
+    repositoryRoot: toPosixPath(scan.repositoryRoot),
+    fileCount: scan.fileCount,
+    stacks: scan.stacks,
+    commands: scan.commands,
+    sections: scan.manifest.sections,
+    written,
+  };
+  if (options.json || options.write) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`Oris Flow scan: ${payload.repositoryRoot}`);
+    console.log(`Files scanned: ${payload.fileCount}`);
+    console.log(`Stacks: ${payload.stacks.map((stack) => stack.label).join(", ") || "none"}`);
+    console.log(`Sections: ${Object.keys(payload.sections).join(", ") || "none"}`);
+  }
+}
+