agent-rules-init 0.6.0 → 0.6.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 agent-rules-init contributors
+Copyright (c) 2026 Rafael Camacho Marchena and agent-rules-init contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,15 +8,19 @@ npx agent-rules-init
 
 The CLI detects JavaScript/TypeScript, Python, Java, PHP, Ruby, Go, Rust, C#/.NET, Kotlin, Swift, Dart/Flutter, C/C++, Elixir, Scala and R projects. It also understands mixed repositories and npm, pnpm, Yarn and Bun workspaces, generating package-scoped `AGENTS.generated.md` files.
 
-All output is written with a `.generated` suffix and existing files are never overwritten. Review the generated files and remove the suffix when you are ready to activate them.
+All output is written with a `.generated` suffix and existing files are never overwritten during generation. Review them and run `--apply` to activate with safe backups.
 
 Use `--lang es` or `--lang en` to select the output language. See the [full documentation](https://github.com/racama29/agent-rules-init#readme) for supported frameworks, generated files and contribution instructions.
 
-Automation is supported through `--dry-run`, `--force`, `--check`, `--json` and `--non-interactive`. Repository defaults, enrichment assistant/model and per-project overrides can be stored in `.agent-rules-init.yml`.
+Automation is supported through `--dry-run`, `--force`, `--apply`, `--check`, `--json` and `--non-interactive`. Repository defaults, enrichment assistant/model and per-project overrides can be stored in `.agent-rules-init.yml`.
+
+Use `--apply` after review to activate staging files; replaced finals are backed up under `.agent-rules-init/backups/`.
 
 Complete generations store a git-ignored hash receipt so `--check` can verify deterministic or enriched active files without rerunning an assistant. Activated final files take precedence over staging during checks.
 
 AI enrichment runs assistants with read-only restrictions and falls back to deterministic output when invocation or validation fails. Review generated files before activation, especially when the repository did not come from a trusted source.
+
+Enrichment also reports batch, retry, input-size, fallback and duration metrics.
 
 Generated documents share an evidence-backed model but are not duplicates: Claude receives broad repository context, AGENTS receives operational commands and scope, and Copilot receives concise implementation conventions. Observed architecture and local conventions include their source files so specific claims can be audited.
 

package/dist/cli.d.ts

@@ -2,7 +2,7 @@ import { type GeneratedFile, type WriteResult } from "./core/writer.js";
 import { type Lang } from "./core/i18n.js";
 import { type AgentRulesConfig } from "./core/config.js";
 import { type PromptFn } from "./core/prompt-engine.js";
-import { type AssistantId, type ExecFn } from "./core/llm-bridge.js";
+import { type AssistantId, type EnrichMetrics, type ExecFn } from "./core/llm-bridge.js";
 import type { RepoFacts } from "./core/types.js";
 export interface RunCliOptions {
     promptFn?: PromptFn;
@@ -25,6 +25,7 @@ export interface RunCliOptions {
     onGeneratedFiles?: (files: readonly GeneratedFile[]) => void;
     /** Receives the deterministic generation fingerprint before optional enrichment. */
     onBaselineHash?: (hash: string) => void;
+    onEnrichMetrics?: (metrics: EnrichMetrics) => void;
     /** Preloaded repository configuration; loaded from disk when omitted. */
     config?: AgentRulesConfig;
     onConfigWarnings?: (warnings: readonly string[]) => void;
@@ -36,6 +37,7 @@ export interface CliRunOptions {
     lang?: Lang;
     dryRun?: true;
     force?: true;
+    apply?: true;
     check?: true;
     json?: true;
     nonInteractive?: true;

package/dist/cli.js

@@ -11,8 +11,10 @@ import { loadConfig } from "./core/config.js";
 import { applyProjectExcludes, buildPackageUnits } from "./core/project-units.js";
 import { renderProjectUnitAgents } from "./core/project-unit-output.js";
 import { collectLowConfidenceQuestions, askQuestions, applyAnswers, makeDefaultPromptFn, hasInteractiveTty, } from "./core/prompt-engine.js";
-import { detectAvailableAssistants, enrichFilesWithAssistant, defaultExecFn, } from "./core/llm-bridge.js";
-import { hashContent, hashGeneratedFiles, loadGenerationState, makeGenerationState, writeGenerationState, } from "./core/generation-state.js";
+import { detectAvailableAssistants, enrichFilesWithAssistant, estimateEnrichment, defaultExecFn, } from "./core/llm-bridge.js";
+import { hashGeneratedFiles, makeGenerationState, writeGenerationState, } from "./core/generation-state.js";
+import { evaluateGenerationCheck } from "./core/check-state.js";
+import { applyGeneratedFiles } from "./core/activation.js";
 import { jsTsPack } from "./packs/js-ts.js";
 import { pythonPack } from "./packs/python.js";
 import { javaPack } from "./packs/java.js";
@@ -150,6 +152,9 @@ export async function runCli(rootPath, options = {}) {
                 proceed = (await clack.confirm({ message: ui.enrichConfirm(chosenAssistant) })) === true;
             }
             if (proceed) {
+                const estimate = estimateEnrichment(files);
+                if (estimate.batches > 1)
+                    notify(ui.enrichLargeInput(estimate.characters, estimate.batches));
                 const spinner = canOfferEnrich ? clack.spinner() : undefined;
                 if (spinner)
                     spinner.start(ui.enrichWorking(chosenAssistant));
@@ -162,6 +167,7 @@ export async function runCli(rootPath, options = {}) {
                     mustKeep: facts.canonical.map((c) => c.command),
                     existingDocs: readExistingDocs(rootPath),
                     model: options.model ?? config.model,
+                    onMetrics: options.onEnrichMetrics,
                 });
                 const changed = enriched.some((file, i) => file.content !== files[i].content);
                 const outcome = changed ? ui.enrichDone : ui.enrichKept;
@@ -217,6 +223,10 @@ export function resolveCliAction(argv) {
             options.force = true;
             continue;
         }
+        if (arg === "--apply") {
+            options.apply = true;
+            continue;
+        }
         if (arg === "--check") {
             options.check = true;
             continue;
@@ -294,7 +304,7 @@ export async function main() {
     }
     const machineOutput = action.json === true;
     const planningOnly = action.dryRun === true || action.check === true;
-    const nonInteractive = action.nonInteractive === true || machineOutput || planningOnly;
+    const nonInteractive = action.nonInteractive === true || machineOutput || planningOnly || action.apply === true;
     // Enrichment output is non-deterministic, so --check (freshness comparison) must stay
     // on the deterministic baseline.
     if (!machineOutput)
@@ -304,13 +314,17 @@ export async function main() {
     }
     try {
         const loadedConfig = loadConfig(process.cwd());
-        const enrich = (action.enrich ?? loadedConfig.config.enrich) === true && action.check !== true;
+        const apply = action.apply === true && action.check !== true && action.dryRun !== true;
+        const configuredEnrich = (action.enrich ?? loadedConfig.config.enrich) === true;
+        const enrich = configuredEnrich && action.check !== true && !(apply && action.force !== true);
         const lang = action.lang ?? loadedConfig.config.lang ?? defaultLang;
         ui = UI[lang];
         if (action.enrich === true && action.check === true)
             console.warn(ui.enrichIgnoredWithCheck);
         if (action.force === true && action.check === true)
             console.warn(ui.forceIgnoredWithCheck);
+        if (action.apply === true && !apply)
+            console.warn(ui.applyIgnoredWithPlanning);
         if (!machineOutput) {
             for (const warning of loadedConfig.warnings)
                 console.warn(warning);
@@ -318,10 +332,11 @@ export async function main() {
         let generatedFiles = [];
         let repoFacts;
         let baselineHash;
+        let enrichMetrics;
         const results = await runCli(process.cwd(), {
             lang,
             config: loadedConfig.config,
-            dryRun: planningOnly,
+            dryRun: planningOnly || (apply && action.force !== true),
             force: action.force === true && action.check !== true,
             nonInteractive,
             skipLlm: nonInteractive && !enrich,
@@ -334,59 +349,43 @@ export async function main() {
             onBaselineHash: (hash) => {
                 baselineHash = hash;
             },
+            onEnrichMetrics: (metrics) => {
+                enrichMetrics = metrics;
+            },
             onFacts: (facts) => {
                 repoFacts = facts;
             },
         });
+        let activationResults = [];
+        if (apply) {
+            if (!baselineHash)
+                throw new Error("generation baseline was not produced");
+            activationResults = applyGeneratedFiles(process.cwd(), generatedFiles, baselineHash);
+        }
         const written = results.filter((r) => r.status === "written");
         const overwritten = results.filter((r) => r.status === "overwritten");
         const changed = [...written, ...overwritten];
         const failures = results.filter((r) => r.status === "error");
-        const generationState = action.check ? loadGenerationState(process.cwd()) : undefined;
-        const baselineMatches = generationState !== undefined && generationState.baselineHash === baselineHash;
-        const fileStates = action.check
-            ? generatedFiles.map((file) => {
-                const activePath = file.path.replace(".generated", "");
-                const stagingAbsolute = path.join(process.cwd(), file.path);
-                const activeAbsolute = path.join(process.cwd(), activePath);
-                const stagingExists = fs.existsSync(stagingAbsolute);
-                const activeExists = fs.existsSync(activeAbsolute);
-                const effectivePath = activeExists ? activePath : stagingExists ? file.path : undefined;
-                const effectiveAbsolute = activeExists ? activeAbsolute : stagingExists ? stagingAbsolute : undefined;
-                const expectedHash = baselineMatches ? generationState?.outputHashes[file.path] : undefined;
-                const current = effectiveAbsolute
-                    ? expectedHash
-                        ? hashContent(fs.readFileSync(effectiveAbsolute, "utf8")) === expectedHash
-                        : fs.readFileSync(effectiveAbsolute, "utf8") === file.content
-                    : false;
-                return { generatedPath: file.path, activePath, stagingExists, activeExists, effectivePath, current };
-            })
-            : [];
-        const missing = action.check
-            ? generatedFiles.filter((file) => !fileStates.find((state) => state.generatedPath === file.path)?.effectivePath)
-            : [];
-        const outdated = action.check
-            ? generationState && !baselineMatches
-                ? [...generatedFiles]
-                : generatedFiles.filter((file) => {
-                    const state = fileStates.find((candidate) => candidate.generatedPath === file.path);
-                    return state?.effectivePath !== undefined && !state.current;
-                })
-            : [];
+        const check = action.check
+            ? evaluateGenerationCheck(process.cwd(), generatedFiles, baselineHash)
+            : { baselineMatches: undefined, recordedBaselineHash: undefined, fileStates: [], missing: [], outdated: [] };
+        const { fileStates, missing, outdated } = check;
         const checkIssues = missing.length + outdated.length;
         if (machineOutput) {
             const contentByPath = new Map(generatedFiles.map((file) => [file.path, file.content]));
             console.log(JSON.stringify({
-                mode: action.check ? "check" : action.dryRun ? "dry-run" : "write",
+                mode: action.check ? "check" : action.dryRun ? "dry-run" : apply ? "apply" : "write",
                 configWarnings: loadedConfig.warnings,
                 facts: repoFacts,
                 wouldCreate: action.check ? missing.length : written.length,
                 missing: missing.map((file) => file.path),
                 outdated: outdated.map((file) => file.path),
-                baselineCurrent: generationState ? baselineMatches : undefined,
+                baselineCurrent: check.baselineMatches,
                 baselineHash,
-                recordedBaselineHash: generationState?.baselineHash,
+                recordedBaselineHash: check.recordedBaselineHash,
                 fileStates,
+                activationResults,
+                enrichMetrics,
                 results: results.map((result) => ({
                     ...result,
                     ...(planningOnly ? { content: contentByPath.get(result.path) } : {}),
@@ -401,6 +400,16 @@ export async function main() {
                 console.log(`\n--- ${file.path} (${label}) ---\n${file.content}`);
             }
         }
+        else if (apply) {
+            for (const result of activationResults) {
+                if (result.status === "applied")
+                    clack.log.success(ui.fileApplied(result.activePath, result.backupPath));
+                else if (result.status === "unchanged")
+                    clack.log.info(ui.fileAlreadyApplied(result.activePath));
+                else if (result.status === "error")
+                    clack.log.warn(`${result.activePath}: ${result.error}`);
+            }
+        }
         else if (!action.check)
             for (const result of results) {
                 if (result.status === "written" || result.status === "overwritten") {
@@ -413,6 +422,8 @@ export async function main() {
                     clack.log.warn(`${result.path}: ${result.error}`);
                 }
             }
+        if (!machineOutput && enrichMetrics)
+            clack.log.info(ui.enrichMetrics(enrichMetrics));
         if (!machineOutput && action.check) {
             console.log(checkIssues > 0
                 ? ui.checkSummary(missing.length, outdated.length)
@@ -421,20 +432,23 @@ export async function main() {
         else if (!machineOutput && action.dryRun) {
             console.log(`\n${ui.dryRunSummary(changed.length)}`);
         }
+        else if (!machineOutput && apply) {
+            clack.outro(ui.outroApplied);
+        }
         else if (!machineOutput && changed.length > 0) {
             clack.outro(ui.outroWritten);
         }
         else if (!machineOutput) {
             clack.outro(ui.outroNothing);
         }
-        if (failures.length > 0 || (action.check && checkIssues > 0)) {
+        if (failures.length > 0 || activationResults.some((result) => result.status === "error") || (action.check && checkIssues > 0)) {
             process.exitCode = 1;
         }
     }
     catch (err) {
         const message = ui.unexpectedError(err.message);
         if (machineOutput) {
-            console.log(JSON.stringify({ mode: action.check ? "check" : action.dryRun ? "dry-run" : "write", error: message }));
+            console.log(JSON.stringify({ mode: action.check ? "check" : action.dryRun ? "dry-run" : action.apply ? "apply" : "write", error: message }));
         }
         else {
             clack.log.error(message);

package/dist/core/activation.d.ts

@@ -0,0 +1,12 @@
+import type { GeneratedFile } from "./writer.js";
+export interface ActivationResult {
+    generatedPath: string;
+    activePath: string;
+    status: "applied" | "unchanged" | "skipped" | "error";
+    backupPath?: string;
+    error?: string;
+}
+export declare class ActivationError extends Error {
+    constructor(message: string);
+}
+export declare function applyGeneratedFiles(rootPath: string, files: readonly GeneratedFile[], baselineHash: string, now?: Date): ActivationResult[];

package/dist/core/activation.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { activePathFor } from "./check-state.js";
+import { hashContent, loadGenerationState, writeGenerationState, } from "./generation-state.js";
+const BACKUP_ROOT = ".agent-rules-init/backups";
+export class ActivationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ActivationError";
+    }
+}
+function assertSafeRegularFile(filePath, label) {
+    if (fs.existsSync(filePath) && fs.lstatSync(filePath).isSymbolicLink()) {
+        throw new ActivationError(`refusing to use a symbolic link as ${label}`);
+    }
+}
+function safeResolve(rootPath, relativePath) {
+    const absolute = path.resolve(rootPath, relativePath);
+    const fromRoot = path.relative(path.resolve(rootPath), absolute);
+    if (fromRoot.startsWith("..") || path.isAbsolute(fromRoot)) {
+        throw new ActivationError("refusing to activate a path outside the repository root");
+    }
+    return absolute;
+}
+function assertParentInside(realRoot, absolutePath) {
+    const realParent = fs.realpathSync(path.dirname(absolutePath));
+    const fromRoot = path.relative(realRoot, realParent);
+    if (fromRoot.startsWith("..") || path.isAbsolute(fromRoot)) {
+        throw new ActivationError("refusing to write through a directory outside the repository root");
+    }
+}
+function availableBackupPath(rootPath, preferredPath) {
+    if (!fs.existsSync(path.resolve(rootPath, preferredPath)))
+        return preferredPath;
+    let suffix = 1;
+    while (fs.existsSync(path.resolve(rootPath, `${preferredPath}.${suffix}`)))
+        suffix++;
+    return `${preferredPath}.${suffix}`;
+}
+export function applyGeneratedFiles(rootPath, files, baselineHash, now = new Date()) {
+    const state = loadGenerationState(rootPath);
+    if (!state)
+        throw new ActivationError("no generation receipt found; run the generator first");
+    if (state.baselineHash !== baselineHash) {
+        throw new ActivationError("the repository changed since generation; run with --force before --apply");
+    }
+    const backupStamp = now.toISOString().replace(/[:.]/g, "-");
+    const realRoot = fs.realpathSync(rootPath);
+    const results = [];
+    let wroteBackupIgnore = false;
+    for (const file of files) {
+        const activePath = activePathFor(file.path);
+        const stagingAbsolute = safeResolve(rootPath, file.path);
+        const activeAbsolute = safeResolve(rootPath, activePath);
+        try {
+            if (!fs.existsSync(stagingAbsolute)) {
+                results.push({ generatedPath: file.path, activePath, status: "skipped" });
+                continue;
+            }
+            assertSafeRegularFile(stagingAbsolute, "generated staging file");
+            assertSafeRegularFile(activeAbsolute, "activated file");
+            const stagingContent = fs.readFileSync(stagingAbsolute, "utf8");
+            const activeContent = fs.existsSync(activeAbsolute)
+                ? fs.readFileSync(activeAbsolute, "utf8")
+                : undefined;
+            if (activeContent === stagingContent) {
+                state.outputHashes[file.path] = hashContent(stagingContent);
+                results.push({ generatedPath: file.path, activePath, status: "unchanged" });
+                continue;
+            }
+            let backupPath;
+            if (activeContent !== undefined) {
+                backupPath = availableBackupPath(rootPath, path.join(BACKUP_ROOT, backupStamp, activePath).split(path.sep).join("/"));
+                const backupAbsolute = safeResolve(rootPath, backupPath);
+                fs.mkdirSync(path.dirname(backupAbsolute), { recursive: true });
+                assertParentInside(realRoot, backupAbsolute);
+                fs.copyFileSync(activeAbsolute, backupAbsolute, fs.constants.COPYFILE_EXCL);
+                if (!wroteBackupIgnore) {
+                    const metadataRoot = path.join(rootPath, ".agent-rules-init");
+                    fs.mkdirSync(metadataRoot, { recursive: true });
+                    const ignorePath = path.join(metadataRoot, ".gitignore");
+                    if (!fs.existsSync(ignorePath))
+                        fs.writeFileSync(ignorePath, "*\n");
+                    wroteBackupIgnore = true;
+                }
+            }
+            fs.mkdirSync(path.dirname(activeAbsolute), { recursive: true });
+            assertParentInside(realRoot, activeAbsolute);
+            fs.writeFileSync(activeAbsolute, stagingContent);
+            state.outputHashes[file.path] = hashContent(stagingContent);
+            results.push({ generatedPath: file.path, activePath, status: "applied", backupPath });
+        }
+        catch (error) {
+            results.push({
+                generatedPath: file.path,
+                activePath,
+                status: "error",
+                error: error.message,
+            });
+        }
+    }
+    writeGenerationState(rootPath, state);
+    return results;
+}

package/dist/core/check-state.d.ts

@@ -0,0 +1,18 @@
+import type { GeneratedFile } from "./writer.js";
+export interface GeneratedFileState {
+    generatedPath: string;
+    activePath: string;
+    stagingExists: boolean;
+    activeExists: boolean;
+    effectivePath?: string;
+    current: boolean;
+}
+export interface GenerationCheck {
+    baselineMatches?: boolean;
+    recordedBaselineHash?: string;
+    fileStates: GeneratedFileState[];
+    missing: GeneratedFile[];
+    outdated: GeneratedFile[];
+}
+export declare function activePathFor(generatedPath: string): string;
+export declare function evaluateGenerationCheck(rootPath: string, files: readonly GeneratedFile[], baselineHash: string | undefined): GenerationCheck;

package/dist/core/check-state.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+import { hashContent, loadGenerationState } from "./generation-state.js";
+export function activePathFor(generatedPath) {
+    return generatedPath.replace(".generated", "");
+}
+export function evaluateGenerationCheck(rootPath, files, baselineHash) {
+    const generationState = loadGenerationState(rootPath);
+    const baselineMatches = generationState
+        ? generationState.baselineHash === baselineHash
+        : undefined;
+    const fileStates = files.map((file) => {
+        const activePath = activePathFor(file.path);
+        const stagingAbsolute = path.join(rootPath, file.path);
+        const activeAbsolute = path.join(rootPath, activePath);
+        const stagingExists = fs.existsSync(stagingAbsolute);
+        const activeExists = fs.existsSync(activeAbsolute);
+        const effectivePath = activeExists ? activePath : stagingExists ? file.path : undefined;
+        const effectiveAbsolute = activeExists ? activeAbsolute : stagingExists ? stagingAbsolute : undefined;
+        const expectedHash = baselineMatches ? generationState?.outputHashes[file.path] : undefined;
+        const current = effectiveAbsolute
+            ? expectedHash
+                ? hashContent(fs.readFileSync(effectiveAbsolute, "utf8")) === expectedHash
+                : fs.readFileSync(effectiveAbsolute, "utf8") === file.content
+            : false;
+        return { generatedPath: file.path, activePath, stagingExists, activeExists, effectivePath, current };
+    });
+    const missing = files.filter((file) => !fileStates.find((state) => state.generatedPath === file.path)?.effectivePath);
+    const outdated = generationState && baselineMatches === false
+        ? [...files]
+        : files.filter((file) => {
+            const state = fileStates.find((candidate) => candidate.generatedPath === file.path);
+            return state?.effectivePath !== undefined && !state.current;
+        });
+    return {
+        baselineMatches,
+        recordedBaselineHash: generationState?.baselineHash,
+        fileStates,
+        missing,
+        outdated,
+    };
+}

package/dist/core/i18n.d.ts

@@ -32,10 +32,13 @@ export interface UiTexts {
     missingFlagValue: (flag: string) => string;
     enrichIgnoredWithCheck: string;
     forceIgnoredWithCheck: string;
+    applyIgnoredWithPlanning: string;
     dryRunFileLabel: (status: "written" | "overwritten" | "skipped" | "error" | undefined) => string;
     dryRunSummary: (changed: number) => string;
     checkSummary: (missing: number, outdated: number) => string;
     checkOk: string;
+    fileApplied: (path: string, backupPath?: string) => string;
+    fileAlreadyApplied: (path: string) => string;
     assistantNotAvailable: (assistant: string) => string;
     noTtyWarning: string;
     skippedQuestion: (message: string) => string;
@@ -48,10 +51,21 @@ export interface UiTexts {
     enrichNoAssistant: string;
     enrichEvidenceDropped: (paths: readonly string[]) => string;
     enrichRetrying: (assistant: string) => string;
+    enrichMetrics: (metrics: {
+        assistant: string;
+        model?: string;
+        batches: number;
+        attempts: number;
+        fallbackBatches: number;
+        inputChars: number;
+        durationMs: number;
+    }) => string;
+    enrichLargeInput: (characters: number, batches: number) => string;
     enrichPrompt: (filesJson: string, mustKeep: readonly string[], existingDocsJson?: string) => string;
     fileSkipped: (path: string) => string;
     outroWritten: string;
     outroNothing: string;
+    outroApplied: string;
     unexpectedError: (message: string) => string;
     cancelled: string;
     dirNotes: Record<string, string>;

package/dist/core/i18n.js

@@ -81,10 +81,11 @@ Uso:
   npx agent-rules-init --version  muestra la versión
 
 Los archivos se crean siempre con sufijo .generated y nunca sobrescriben nada existente:
-revisa su contenido y quita el sufijo para activarlos.`,
+revisa su contenido y ejecuta --apply para activarlos con backup seguro.`,
         automationUsage: `Automatización:
   --dry-run         renderiza y muestra archivos sin escribir
   --force           regenera solo archivos *.generated.*; nunca sobrescribe los finales
+  --apply           activa los archivos generados; guarda backup de los finales reemplazados
   --check           falla si los archivos generados o activados faltan o están obsoletos; nunca escribe
   --json            emite un único resultado JSON legible por máquinas
   --non-interactive omite preguntas y la oferta de enriquecimiento con IA
@@ -97,10 +98,13 @@ revisa su contenido y quita el sufijo para activarlos.`,
         missingFlagValue: (flag) => `La opción ${flag} requiere un valor.`,
         enrichIgnoredWithCheck: "--enrich se ignora con --check.",
         forceIgnoredWithCheck: "--force se ignora con --check.",
+        applyIgnoredWithPlanning: "--apply se ignora con --check o --dry-run.",
         dryRunFileLabel: (status) => status === "written" ? "se crearía" : status === "overwritten" ? "se actualizaría" : "ya existe",
         dryRunSummary: (changed) => `${changed} archivo(s) se crearían o actualizarían.`,
         checkSummary: (missing, outdated) => `${missing} archivo(s) ausentes; ${outdated} archivo(s) obsoletos.`,
         checkOk: "Los archivos generados o activados están presentes y actualizados.",
+        fileApplied: (path, backupPath) => backupPath ? `${path} activado (backup: ${backupPath}).` : `${path} activado.`,
+        fileAlreadyApplied: (path) => `${path}: ya estaba actualizado.`,
         assistantNotAvailable: (assistant) => `Se pidió ${assistant} con --assistant pero no está instalado; se conserva la versión generada.`,
         noTtyWarning: "No se detectó una terminal interactiva (esto pasa a veces en Git Bash en Windows). " +
             "Continuando sin preguntas ni oferta de enriquecimiento con IA; se usarán los valores detectados.",
@@ -114,6 +118,10 @@ revisa su contenido y quita el sufijo para activarlos.`,
         enrichNoAssistant: "Se pidió --enrich pero no se encontró ningún asistente (claude o codex) instalado; se conserva la versión generada.",
         enrichEvidenceDropped: (paths) => `Se descartaron afirmaciones del enriquecimiento porque su evidencia citada no existe en el repo: ${paths.join(", ")}`,
         enrichRetrying: (assistant) => `La respuesta de ${assistant} no pasó la validación; se reintenta una vez…`,
+        enrichMetrics: (metrics) => `Enriquecimiento: ${metrics.assistant}${metrics.model ? `/${metrics.model}` : ""}, ${metrics.batches} lote(s), ` +
+            `${metrics.attempts} intento(s), ${metrics.inputChars} caracteres enviados, ${metrics.fallbackBatches} fallback(s), ` +
+            `${(metrics.durationMs / 1000).toFixed(1)} s.`,
+        enrichLargeInput: (characters, batches) => `El enriquecimiento enviará aproximadamente ${characters} caracteres en ${batches} procesos; revisa el modelo elegido y su coste.`,
         enrichPrompt: (filesJson, mustKeep, existingDocsJson) => "Estás ejecutándote en la raíz de un repositorio. Los siguientes archivos de instrucciones para agentes de IA " +
             "se generaron solo a partir de manifiestos, CI y configuración, por lo que algunas secciones (convenciones, arquitectura, prompts) son genéricas.\n" +
             "Primero investiga el repositorio real con tus herramientas de lectura: configuración de estilo (linter, formatter, pre-commit), " +
@@ -135,10 +143,9 @@ revisa su contenido y quita el sufijo para activarlos.`,
             "Devuelve únicamente un array JSON válido con exactamente los mismos objetos path/content y en el mismo orden, sin bloque de código ni comentarios. " +
             `Entrada JSON:\n${filesJson}`,
         fileSkipped: (path) => `${path}: ya existía, se conserva sin cambios.`,
-        outroWritten: "Revisa los archivos *.generated.* y, cuando estés conforme, quita el sufijo " +
-            '".generated" (ej. "CLAUDE.generated.md" → "CLAUDE.md") para activarlos — ' +
-            "tu asistente de IA solo lee el nombre final, no el generado.",
+        outroWritten: "Revisa los archivos *.generated.* y ejecuta `npx agent-rules-init --apply` para activarlos con backup seguro.",
         outroNothing: "No se generó ningún archivo nuevo.",
+        outroApplied: "Archivos revisados activados. Los asistentes ya pueden leer los nombres finales.",
         unexpectedError: (message) => `Fallo inesperado: ${message}`,
         cancelled: "Operación cancelada.",
         dirNotes: {
@@ -193,10 +200,11 @@ Usage:
   npx agent-rules-init --version  show the version
 
 Files are always created with the .generated suffix and never overwrite anything:
-review their content and drop the suffix to activate them.`,
+review their content and run --apply to activate them with safe backups.`,
         automationUsage: `Automation:
   --dry-run         render and print files without writing
   --force           refresh only *.generated.* files; never overwrite activated final files
+  --apply           activate generated files; back up any replaced final files
   --check           fail when generated or activated files are missing/outdated; never write
   --json            emit a single machine-readable JSON result
   --non-interactive skip questions and the AI-enrichment offer
@@ -209,10 +217,13 @@ review their content and drop the suffix to activate them.`,
         missingFlagValue: (flag) => `The ${flag} option requires a value.`,
         enrichIgnoredWithCheck: "--enrich is ignored with --check.",
         forceIgnoredWithCheck: "--force is ignored with --check.",
+        applyIgnoredWithPlanning: "--apply is ignored with --check or --dry-run.",
         dryRunFileLabel: (status) => status === "written" ? "would create" : status === "overwritten" ? "would update" : "exists",
         dryRunSummary: (changed) => `${changed} file(s) would be created or updated.`,
         checkSummary: (missing, outdated) => `${missing} file(s) missing; ${outdated} file(s) outdated.`,
         checkOk: "Generated or activated files are present and up to date.",
+        fileApplied: (path, backupPath) => backupPath ? `${path} activated (backup: ${backupPath}).` : `${path} activated.`,
+        fileAlreadyApplied: (path) => `${path}: already up to date.`,
         assistantNotAvailable: (assistant) => `${assistant} was requested with --assistant but is not installed; keeping the generated version.`,
         noTtyWarning: "No interactive terminal detected (this sometimes happens in Git Bash on Windows). " +
             "Continuing without questions or the AI-enrichment offer; detected values will be used.",
@@ -226,6 +237,10 @@ review their content and drop the suffix to activate them.`,
         enrichNoAssistant: "--enrich was requested but no installed assistant (claude or codex) was found; keeping the generated version.",
         enrichEvidenceDropped: (paths) => `Dropped enrichment claims because their cited evidence does not exist in the repo: ${paths.join(", ")}`,
         enrichRetrying: (assistant) => `${assistant}'s response failed validation; retrying once…`,
+        enrichMetrics: (metrics) => `Enrichment: ${metrics.assistant}${metrics.model ? `/${metrics.model}` : ""}, ${metrics.batches} batch(es), ` +
+            `${metrics.attempts} attempt(s), ${metrics.inputChars} characters sent, ${metrics.fallbackBatches} fallback(s), ` +
+            `${(metrics.durationMs / 1000).toFixed(1)} s.`,
+        enrichLargeInput: (characters, batches) => `Enrichment will send approximately ${characters} characters across ${batches} processes; review the chosen model and its cost.`,
         enrichPrompt: (filesJson, mustKeep, existingDocsJson) => "You are running at the root of a repository. The following instruction files for AI agents were generated " +
             "from manifests, CI and configuration only, so some sections (conventions, architecture, prompts) are generic.\n" +
             "First investigate the actual repository with your read tools: style configuration (linter, formatter, pre-commit), " +
@@ -247,10 +262,9 @@ review their content and drop the suffix to activate them.`,
             "Return only a valid JSON array with exactly the same path/content objects in the same order, without a code fence or commentary. " +
             `Input JSON:\n${filesJson}`,
         fileSkipped: (path) => `${path}: already existed, left unchanged.`,
-        outroWritten: "Review the *.generated.* files and, once you are happy with them, drop the " +
-            '".generated" suffix (e.g. "CLAUDE.generated.md" → "CLAUDE.md") to activate them — ' +
-            "your AI assistant only reads the final name, not the generated one.",
+        outroWritten: "Review the *.generated.* files, then run `npx agent-rules-init --apply` to activate them with safe backups.",
         outroNothing: "No new files were generated.",
+        outroApplied: "Reviewed files activated. Assistants can now read the final names.",
         unexpectedError: (message) => `Unexpected failure: ${message}`,
         cancelled: "Operation cancelled.",
         dirNotes: {

package/dist/core/llm-bridge.d.ts

@@ -19,6 +19,21 @@ export interface EnrichOptions {
     existingDocs?: readonly GeneratedFile[];
     /** Model identifier forwarded verbatim to the assistant CLI; its default when omitted. */
     model?: string;
+    onMetrics?: (metrics: EnrichMetrics) => void;
+}
+export declare function estimateEnrichment(files: readonly GeneratedFile[]): {
+    characters: number;
+    batches: number;
+};
+export interface EnrichMetrics {
+    assistant: AssistantId;
+    model?: string;
+    batches: number;
+    attempts: number;
+    fallbackBatches: number;
+    inputChars: number;
+    outputChars: number;
+    durationMs: number;
 }
 /**
  * Asks the assistant to investigate the repository it runs in and rewrite the generated

package/dist/core/llm-bridge.js

@@ -128,6 +128,9 @@ function parseAssistantBatch(stdout, originals) {
         return { path: originals[index].path, content: entry.content };
     });
 }
+export function estimateEnrichment(files) {
+    return { characters: JSON.stringify(files).length, batches: makeBatches(files).length };
+}
 // The assistant is free-form: it may drop the one command CI actually runs and invent a
 // plausible replacement. Any lost must-keep command invalidates the whole batch.
 function assertMustKeepSurvive(enriched, originals, mustKeep) {
@@ -139,7 +142,37 @@ function assertMustKeepSurvive(enriched, originals, mustKeep) {
         }
     }
 }
+const DANGEROUS_INSTRUCTION = /(?:rm\s+-rf|git\s+reset\s+--hard|curl[^\n|]*\|\s*(?:sh|bash)|invoke-expression|chmod\s+777|sudo\s+)/i;
+const NEGATED_DANGER = /(?:never|do not|don't|must not|avoid|nunca|no ejecutes|no ejecutar|evita)/i;
+function assertNoNewDangerousInstructions(enriched, originals) {
+    const originalText = originals.map((file) => file.content).join("\n");
+    for (const line of enriched.flatMap((file) => file.content.split("\n"))) {
+        const dangerous = line.match(DANGEROUS_INSTRUCTION)?.[0];
+        if (dangerous && !NEGATED_DANGER.test(line) && !originalText.includes(dangerous)) {
+            throw new Error(`assistant introduced a dangerous instruction: ${dangerous}`);
+        }
+    }
+}
+function assertNewBulletClaimsCiteEvidence(enriched, originals) {
+    for (let index = 0; index < enriched.length; index++) {
+        const originalLines = new Set(originals[index].content.split("\n").map((line) => line.trim()));
+        for (const line of enriched[index].content.split("\n")) {
+            const trimmed = line.trim();
+            if (/^[-*] /.test(trimmed) && !originalLines.has(trimmed) && !HAS_EVIDENCE_GROUP.test(trimmed)) {
+                throw new Error("assistant introduced a bullet claim without cited evidence");
+            }
+        }
+    }
+}
+function assistantFailureDetail(assistant, error) {
+    const message = error.message;
+    if (/unknown (?:option|argument)|unrecognized (?:option|argument)|unexpected argument/i.test(message)) {
+        return `${assistant} does not support the required read-only safety flags; update the assistant CLI`;
+    }
+    return message;
+}
 const EVIDENCE_GROUP = /\((?:evidencia|evidence):([^)]*)\)/gi;
+const HAS_EVIDENCE_GROUP = /\((?:evidencia|evidence):[^)]*\)/i;
 // A checkable citation is a plain relative path; tokens with spaces, URLs or globs are
 // left alone rather than guessed at.
 const PATH_TOKEN = /^[\w.@~-]+(?:[\\/][\w.@~-]+)*[\\/]?$/;
@@ -181,20 +214,32 @@ function dropUnverifiableClaims(files, rootPath) {
  * process; only very large outputs are split. Falls back to the originals per batch.
  */
 export async function enrichFilesWithAssistant(assistant, files, options = {}) {
-    const { execFn = defaultExecFn, lang = "es", cwd, mustKeep = [], existingDocs = [], model } = options;
+    const { execFn = defaultExecFn, lang = "es", cwd, mustKeep = [], existingDocs = [], model, onMetrics } = options;
     const existingDocsJson = existingDocs.length > 0 ? JSON.stringify(existingDocs) : undefined;
     const enriched = [];
-    for (const batch of makeBatches(files)) {
+    const batches = makeBatches(files);
+    const startedAt = Date.now();
+    let attempts = 0;
+    let fallbackBatches = 0;
+    let inputChars = 0;
+    let outputChars = 0;
+    for (const batch of batches) {
         const input = UI[lang].enrichPrompt(JSON.stringify(batch), mustKeep, existingDocsJson);
+        let attemptInput = input;
         // Contract violations (invalid JSON, changed paths, dropped commands) are stochastic,
         // especially with smaller models; one bounded retry recovers most of them.
         let attemptsLeft = 2;
         while (attemptsLeft > 0) {
             attemptsLeft--;
+            attempts++;
+            inputChars += attemptInput.length;
             try {
-                const result = await execFn(assistant, printArgs(assistant, model), input, cwd);
+                const result = await execFn(assistant, printArgs(assistant, model), attemptInput, cwd);
+                outputChars += result.stdout.length;
                 let parsed = parseAssistantBatch(result.stdout, batch);
                 assertMustKeepSurvive(parsed, batch, mustKeep);
+                assertNoNewDangerousInstructions(parsed, batch);
+                assertNewBulletClaimsCiteEvidence(parsed, batch);
                 if (cwd) {
                     const verified = dropUnverifiableClaims(parsed, cwd);
                     if (verified.missing.length > 0)
@@ -206,14 +251,27 @@ export async function enrichFilesWithAssistant(assistant, files, options = {}) {
             }
             catch (err) {
                 if (attemptsLeft > 0) {
+                    const detail = assistantFailureDetail(assistant, err);
+                    attemptInput = `${input}\n\nYour previous response was rejected: ${detail}. Correct that exact problem and return the required JSON array only.`;
                     console.warn(UI[lang].enrichRetrying(assistant));
                 }
                 else {
-                    console.warn(UI[lang].enrichFailed(assistant, err.message));
+                    console.warn(UI[lang].enrichFailed(assistant, assistantFailureDetail(assistant, err)));
+                    fallbackBatches++;
                     enriched.push(...batch);
                 }
             }
         }
     }
+    onMetrics?.({
+        assistant,
+        model,
+        batches: batches.length,
+        attempts,
+        fallbackBatches,
+        inputChars,
+        outputChars,
+        durationMs: Date.now() - startedAt,
+    });
     return enriched;
 }

package/dist/core/scanner.js

@@ -6,6 +6,7 @@ const IGNORED_DIRS = new Set([
     ".venv", "venv", ".tox", "__pycache__",
     ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
     ".gradle", ".dart_tool",
+    ".agent-rules-init",
 ]);
 const MAX_DEPTH = 4;
 function walk(rootPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-rules-init",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Generates CLAUDE.md, AGENTS.md, copilot-instructions.md and prompt files from what your repo actually is.",
   "license": "MIT",
   "type": "module",
@@ -35,12 +35,13 @@
   "engines": {
     "node": ">=18"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run lint && npm test && npm run build"
-  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test:enrich": "npm run build && node scripts/smoke-enrichment.mjs",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
     "yaml": "^2.9.0"