zurik 2.1.0 → 3.0.0

package/bin/zurik.js

@@ -4,7 +4,7 @@ import fs from "fs";
 import path from "path";
 import * as readline from "readline";
 import { fileURLToPath } from "url";
-import { init, encrypt, decrypt, status, resolveRoot, ZurikError, ERROR_CODES, MIN_PASSWORD_LENGTH } from "../lib/index.js";
+import { init, encrypt, decrypt, status, ZurikError, ERROR_CODES, MIN_PASSWORD_LENGTH } from "../lib/index.js";
 
 const PKG_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "utf8")).version;
@@ -12,11 +12,11 @@ const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "
 const EXIT = { OK: 0, ERROR: 1, USAGE: 2 };
 const COMMANDS = { init: "init", encrypt: "encrypt", "-e": "encrypt", decrypt: "decrypt", "-d": "decrypt", status: "status", "-s": "status", skill: "skill", help: "help" };
 
-const HELP = `zurik ${VERSION} — encrypt project secrets into a single .zurik bundle
+const HELP = `zurik ${VERSION} — encrypt project secrets into a single .zurik file
 
 Usage:
-  zurik init     [options]   Find .env files and add them to .gitencrypt (creates it)
-  zurik encrypt  [options]   Encrypt files listed in .gitencrypt into .zurik   (alias: -e)
+  zurik init     [options]   Find .env files and list them in .zurik (creates it)
+  zurik encrypt  [options]   Encrypt the files listed in .zurik                (alias: -e)
   zurik decrypt  [options]   Restore files from .zurik                         (alias: -d)
   zurik status   [options]   Show which files are in sync, without decrypting   (alias: -s)
   zurik skill                Print instructions for AI agents (SKILL.md)
@@ -28,6 +28,7 @@ Options:
   --password-stdin           Read the password from the first line of stdin
   --password-file <path>     Read the password from a file
   -f, --force                Decrypt: overwrite local files that differ from .zurik
+  --rekey                    Encrypt: change the password (new salt, re-encrypts every file)
   -n, --dry-run              Report what would happen without writing anything
   --json                     Print one JSON object on stdout (results and errors)
   --no-input                 Never prompt; fail with E_NO_PASSWORD instead
@@ -41,15 +42,16 @@ a terminal (never with --json, --no-input or $CI). Encrypting needs ${MIN_PASSWO
 init needs no password. In a terminal it lets you pick the files (all selected by default);
 otherwise (--json, --no-input, $CI or piped stdin) it adds every .env file found.
 
-zurik uses the nearest parent directory containing .gitencrypt (encrypt), .zurik (decrypt)
-or either (status). Exit codes: 0 success, 1 error, 2 usage error.`;
+.zurik lists one "--- <path>" section per file; add or delete sections to change what is
+encrypted. zurik uses the nearest parent directory containing .zurik.
+Exit codes: 0 success, 1 error, 2 usage error.`;
 
 function usageError(message) {
   return new ZurikError("E_USAGE", message);
 }
 
 function parseArgs(argv) {
-  const opts = { command: null, json: false, force: false, dryRun: false, noInput: false, help: false, version: false };
+  const opts = { command: null, json: false, force: false, rekey: false, dryRun: false, noInput: false, help: false, version: false };
 
   // Support --flag=value for long options.
   const args = argv.flatMap(a => (a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a]));
@@ -81,6 +83,7 @@ function parseArgs(argv) {
       case "--password-stdin": opts.passwordStdin = true; break;
       case "--password-file": opts.passwordFile = takeValue(i++, a); break;
       case "-f": case "--force": opts.force = true; break;
+      case "--rekey": opts.rekey = true; break;
       case "-n": case "--dry-run": opts.dryRun = true; break;
       case "--json": opts.json = true; break;
       case "--no-input": opts.noInput = true; break;
@@ -165,7 +168,7 @@ function selectFiles(items) {
 
     const draw = () => {
       const lines = [
-        "Select files to add to .gitencrypt (up/down move, space toggle, a all/none, enter confirm):",
+        "Select files to encrypt with zurik (up/down move, space toggle, a all/none, enter confirm):",
         ...items.map((p, i) => `${i === cursor ? ">" : " "} [${selected[i] ? "x" : " "}] ${p}`),
       ];
       if (drawn) out.write(`\x1b[${drawn}A`);
@@ -234,20 +237,20 @@ function printHuman(result) {
   const log = (s) => process.stdout.write(s + "\n");
 
   if (result.command === "init") {
-    log(!result.created ? "Using existing .gitencrypt" : result.dryRun ? "[dry run] would create .gitencrypt" : "Created .gitencrypt");
+    log(!result.created ? "Using existing .zurik" : result.dryRun ? "[dry run] would create .zurik" : "Created .zurik");
     for (const f of result.files) log(`  ${f.action === "added" ? prefix : ""}${f.action.padEnd(14)}  ${f.path}`);
-    if (result.files.length === 0) log("No .env files found. Add the paths of your secret files to .gitencrypt.");
-    log("Next: run 'zurik encrypt' and commit .zurik and .gitencrypt.");
+    if (result.files.length === 0) log('No .env files found. Add a "--- <path>" line to .zurik for each secret file.');
+    log("Next: run 'zurik encrypt' and commit .zurik.");
   } else if (result.command === "encrypt") {
-    for (const f of result.files) log(`  ${prefix}encrypted  ${f.path}`);
+    for (const f of result.files) log(`  ${f.action === "unchanged" ? "" : prefix}${f.action.padEnd(9)}  ${f.path}`);
     if (result.gitignoreAdded.length) log(`  ${prefix}added to .gitignore: ${result.gitignoreAdded.join(", ")}`);
-    log(`${result.dryRun ? "Would encrypt" : "Encrypted"} ${result.files.length} file(s) into .zurik`);
+    const changed = result.files.filter(f => f.action === "encrypted").length;
+    log(`${result.dryRun ? "Would encrypt" : "Encrypted"} ${changed} file(s) into .zurik, ${result.files.length - changed} unchanged`);
   } else if (result.command === "decrypt") {
     for (const f of result.files) log(`  ${f.action === "unchanged" ? "" : prefix}${f.action.padEnd(9)}  ${f.path}`);
     log(`${result.dryRun ? "Would decrypt" : "Decrypted"} ${result.files.length} file(s) from .zurik`);
   } else if (result.command === "status") {
-    if (!result.bundleExists) log("No .zurik bundle yet.");
-    for (const f of result.files) log(`  ${f.state.padEnd(15)}  ${f.path}${f.listed ? "" : "  (not in .gitencrypt)"}`);
+    for (const f of result.files) log(`  ${f.state.padEnd(15)}  ${f.path}`);
     log(result.inSync ? "All files in sync." : "Out of sync.");
   }
 }
@@ -258,9 +261,9 @@ function helpSpec() {
     version: VERSION,
     commands: {
       init: { options: ["dryRun", "cwd"], password: false, result: "{ created, files: [{ path, action: 'added'|'already-listed'|'skipped' }] }", note: "Adds every .env file found unless run interactively in a terminal" },
-      encrypt: { options: ["password*", "dryRun", "cwd"], result: "{ files: [{ path, action: 'encrypted' }], gitignoreAdded: [path] }" },
+      encrypt: { options: ["password*", "rekey", "dryRun", "cwd"], result: "{ files: [{ path, action: 'encrypted'|'unchanged' }], gitignoreAdded: [path] }" },
       decrypt: { options: ["password*", "force", "dryRun", "cwd"], result: "{ files: [{ path, action: 'created'|'updated'|'unchanged' }] }" },
-      status: { options: ["password (only if .zurik exists)", "cwd"], result: "{ bundleExists, inSync, files: [{ path, state: 'in-sync'|'modified'|'missing-locally'|'not-in-bundle'|'missing', listed }] }" },
+      status: { options: ["password (only once something is encrypted)", "cwd"], result: "{ inSync, files: [{ path, state: 'in-sync'|'modified'|'missing-locally'|'not-in-bundle'|'missing' }] }" },
     },
     passwordSources: ["--password <value>", "--password-file <path>", "--password-stdin", "$ZURIK_PASSWORD", "$ZURIK_PASSWORD_FILE"],
     minPasswordLength: MIN_PASSWORD_LENGTH,
@@ -279,11 +282,16 @@ async function runInit(opts, base) {
 }
 
 async function runWithPassword(opts, base) {
-  // status only needs a password when there is a bundle to compare against.
-  const needsPassword =
-    opts.command !== "status" || fs.existsSync(path.join(resolveRoot("status", base), ".zurik"));
-  const password = needsPassword ? await resolvePassword(opts) : undefined;
-  if (needsPassword && !password) {
+  // status only needs a password once something is encrypted; it says so with E_NO_PASSWORD.
+  if (opts.command === "status") {
+    try {
+      return await status(base);
+    } catch (err) {
+      if (err.code !== "E_NO_PASSWORD") throw err;
+    }
+  }
+  const password = await resolvePassword(opts);
+  if (!password) {
     throw new ZurikError(
       "E_NO_PASSWORD",
       "No password provided. Use --password-file, --password-stdin, $ZURIK_PASSWORD or -p."
@@ -291,7 +299,7 @@ async function runWithPassword(opts, base) {
   }
 
   const run = { encrypt, decrypt, status }[opts.command];
-  return run({ ...base, password, force: opts.force, dryRun: opts.dryRun });
+  return run({ ...base, password, force: opts.force, rekey: opts.rekey, dryRun: opts.dryRun });
 }
 
 // ---------- main ----------

package/lib/bundle.js

@@ -1,58 +1,74 @@
 import fs from "fs";
 import path from "path";
-import { decryptData } from "./crypto.js";
+import { deriveKey, open, HEADER_PREFIX } from "./crypto.js";
 import { ZurikError } from "./errors.js";
 import { safeRelativePath } from "./paths.js";
 
-export const LIST_FILE = ".gitencrypt";
 export const BUNDLE_FILE = ".zurik";
+const SECTION = "--- ";
+const BASE64 = /^[A-Za-z0-9+/]+=*$/;
 
-// Bundles from older versions carry no modes; secrets default to owner-only.
-const DEFAULT_MODE = 0o600;
-
-// Paths listed in .gitencrypt, normalized and de-duplicated. `null` if the file doesn't exist.
-export function readFileList(root) {
-  const listPath = path.join(root, LIST_FILE);
-  if (!fs.existsSync(listPath)) return null;
-
-  return [
-    ...new Set(
-      fs
-        .readFileSync(listPath, "utf8")
-        .split("\n")
-        .map(x => x.trim())
-        .filter(x => x && !x.startsWith("#"))
-        .map(f => safeRelativePath(f, root))
-    ),
-  ];
+// .zurik is plain text: a header line (once anything is encrypted), then one section per file.
+// A section's data line is empty until the file is first encrypted.
+//
+//   zurik3 scrypt logN=17 r=8 p=1 salt=...
+//
+//   --- .env
+//   <base64>
+//
+//   --- api/.env.production
+//
+// Each file is its own line, so git diffs and merges per file.
+
+const corrupt = (why) => new ZurikError("E_CORRUPT", `Invalid ${BUNDLE_FILE}: ${why}`);
+
+// { header: string | null, files: [{ path, data }] }, or null if .zurik doesn't exist.
+export function readBundle(root) {
+  const file = path.join(root, BUNDLE_FILE);
+  if (!fs.existsSync(file)) return null;
+
+  let header = null;
+  const files = [];
+  const lines = fs.readFileSync(file, "utf8").split("\n").map(l => l.trim());
+
+  lines.forEach((line, i) => {
+    const last = files[files.length - 1];
+    if (line === "") return;
+    if (line.startsWith(SECTION)) {
+      const p = safeRelativePath(line.slice(SECTION.length).trim(), root);
+      if (files.some(f => f.path === p)) throw corrupt(`${p} is listed twice`);
+      files.push({ path: p, data: "" });
+    } else if (line.startsWith(HEADER_PREFIX) && header === null && !last) {
+      header = line;
+    } else if (last && last.data === "" && BASE64.test(line)) {
+      last.data = line;
+    } else if (!last && header === null && (line.startsWith("zurik2:") || BASE64.test(line))) {
+      throw new ZurikError(
+        "E_OLD_FORMAT",
+        `${BUNDLE_FILE} was written by zurik 2.x or earlier. Run 'npx zurik@2 decrypt', delete ${BUNDLE_FILE} ` +
+          "and .gitencrypt, then 'zurik init' and 'zurik encrypt'."
+      );
+    } else {
+      throw corrupt(`unexpected content on line ${i + 1}`);
+    }
+  });
+
+  if (header === null && files.some(f => f.data)) throw corrupt("encrypted data without a header line");
+  return { header, files };
+}
+
+export function writeBundle(root, { header, files }) {
+  const sections = files.map(f => `${SECTION}${f.path}\n${f.data ? f.data + "\n" : ""}`);
+  const text = [header && header + "\n", ...sections].filter(Boolean).join("\n");
+  fs.writeFileSync(path.join(root, BUNDLE_FILE), text);
 }
 
-// Decrypts .zurik and returns [{ path, content: Buffer, mode }]. Every path is validated.
-export async function readBundle(root, password) {
-  const bundlePath = path.join(root, BUNDLE_FILE);
-  if (!fs.existsSync(bundlePath)) {
-    throw new ZurikError("E_NO_BUNDLE", `${BUNDLE_FILE} not found in ${root}`);
-  }
-
-  const plaintext = await decryptData(fs.readFileSync(bundlePath, "utf8"), password);
-
-  let data;
-  try {
-    data = JSON.parse(plaintext);
-  } catch {
-    throw new ZurikError("E_CORRUPT", "Invalid .zurik bundle");
-  }
-  if (!data || typeof data.files !== "object" || data.files === null) {
-    throw new ZurikError("E_CORRUPT", "Invalid .zurik bundle");
-  }
-
-  const modes = data.modes && typeof data.modes === "object" ? data.modes : {};
-
-  return Object.entries(data.files).map(([filePath, base64]) => ({
-    path: safeRelativePath(filePath, root),
-    content: Buffer.from(base64, "base64"),
-    mode: Number.isInteger(modes[filePath]) ? modes[filePath] & 0o777 : DEFAULT_MODE,
-  }));
+// Decrypts every encrypted section: [{ path, content: Buffer, mode }]. Empty sections are skipped.
+export async function openBundle(bundle, password) {
+  const sealed = bundle.files.filter(f => f.data);
+  if (sealed.length === 0) return [];
+  const key = await deriveKey(bundle.header, password);
+  return sealed.map(f => ({ path: f.path, ...open(key, bundle.header, f.path, f.data) }));
 }
 
 // "missing" | "same" | "different" for a local file compared with `content`.

package/lib/crypto.js

@@ -1,103 +1,66 @@
 import crypto from "crypto";
 import { ZurikError } from "./errors.js";
 
+// One key per bundle, derived from the password with the scrypt parameters and salt in the header line:
+//   zurik3 scrypt logN=17 r=8 p=1 salt=<base64, 16 bytes>
+// Each file is sealed on its own with AES-256-GCM: base64( iv(12) | tag(16) | ciphertext ),
+// where the plaintext is mode (2 bytes, big-endian) | content. The header line and the file's path
+// are authenticated as additional data, so the KDF parameters can't be weakened and a block can't
+// be moved to another path.
 const ALGO = "aes-256-gcm";
-const SALT_LENGTH = 16;
+const IV_LENGTH = 12;
 const TAG_LENGTH = 16;
-
-// Current format: "zurik2:" + base64( logN | r | p | salt(16) | iv(12) | tag(16) | ciphertext )
-// The KDF params are authenticated as GCM additional data, so they can't be altered.
-const V2_PREFIX = "zurik2:";
-const V2_IV_LENGTH = 12;
 const KDF = { logN: 17, r: 8, p: 1 }; // N = 2^17 ≈ 128 MiB of memory per guess
 
 // Upper bounds so a crafted file can't make decryption allocate gigabytes.
 const MAX_KDF = { logN: 20, r: 16, p: 4 };
+const HEADER = /^zurik3 scrypt logN=(\d+) r=(\d+) p=(\d+) salt=([A-Za-z0-9+/]{22}==)$/;
 
+export const HEADER_PREFIX = "zurik3 ";
 export const MIN_PASSWORD_LENGTH = 16;
 
-function deriveKey(password, salt, { logN, r, p }) {
+export function newHeader() {
+  return `zurik3 scrypt logN=${KDF.logN} r=${KDF.r} p=${KDF.p} salt=${crypto.randomBytes(16).toString("base64")}`;
+}
+
+export function deriveKey(header, password) {
+  const m = HEADER.exec(header);
+  const [logN, r, p] = m ? m.slice(1, 4).map(Number) : [];
+  if (!m || logN < 1 || logN > MAX_KDF.logN || r < 1 || r > MAX_KDF.r || p < 1 || p > MAX_KDF.p) {
+    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file: invalid or unsupported header");
+  }
   const N = 2 ** logN;
   return new Promise((resolve, reject) => {
-    crypto.scrypt(password, salt, 32, { N, r, p, maxmem: 2 * 128 * N * r + 1024 * 1024 }, (err, key) => {
+    crypto.scrypt(password, Buffer.from(m[4], "base64"), 32, { N, r, p, maxmem: 2 * 128 * N * r + 1024 * 1024 }, (err, key) => {
       if (err) reject(err);
       else resolve(key);
     });
   });
 }
 
-export async function encryptData(data, password) {
-  const params = Buffer.from([KDF.logN, KDF.r, KDF.p]);
-  const salt = crypto.randomBytes(SALT_LENGTH);
-  const iv = crypto.randomBytes(V2_IV_LENGTH);
-  const key = await deriveKey(password, salt, KDF);
+const aad = (header, filePath) => Buffer.from(`${header}\n${filePath}`, "utf8");
 
+export function seal(key, header, filePath, { content, mode }) {
+  const iv = crypto.randomBytes(IV_LENGTH);
   const cipher = crypto.createCipheriv(ALGO, key, iv);
-  cipher.setAAD(params);
-  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
-  const tag = cipher.getAuthTag();
-
-  return V2_PREFIX + Buffer.concat([params, salt, iv, tag, encrypted]).toString("base64");
+  cipher.setAAD(aad(header, filePath));
+  const modeBytes = Buffer.alloc(2);
+  modeBytes.writeUInt16BE(mode & 0o777);
+  const encrypted = Buffer.concat([cipher.update(modeBytes), cipher.update(content), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), encrypted]).toString("base64");
 }
 
-export async function decryptData(text, password) {
-  text = text.trim();
-  return text.startsWith(V2_PREFIX)
-    ? decryptV2(text.slice(V2_PREFIX.length), password)
-    : decryptV1(text, password);
-}
-
-async function decryptV2(base64, password) {
-  const buffer = Buffer.from(base64, "base64");
-  const headerLength = 3 + SALT_LENGTH + V2_IV_LENGTH + TAG_LENGTH;
-  if (buffer.length < headerLength) {
-    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file");
-  }
-
-  const params = buffer.subarray(0, 3);
-  const kdf = { logN: params[0], r: params[1], p: params[2] };
-  if (
-    kdf.logN < 1 || kdf.logN > MAX_KDF.logN ||
-    kdf.r < 1 || kdf.r > MAX_KDF.r ||
-    kdf.p < 1 || kdf.p > MAX_KDF.p
-  ) {
-    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file: unsupported key derivation parameters");
-  }
-
-  let offset = 3;
-  const salt = buffer.subarray(offset, (offset += SALT_LENGTH));
-  const iv = buffer.subarray(offset, (offset += V2_IV_LENGTH));
-  const tag = buffer.subarray(offset, (offset += TAG_LENGTH));
-  const ciphertext = buffer.subarray(offset);
-
-  const key = await deriveKey(password, salt, kdf);
-  const decipher = crypto.createDecipheriv(ALGO, key, iv);
-  decipher.setAAD(params);
-  decipher.setAuthTag(tag);
-  return finish(decipher, ciphertext);
-}
-
-// Legacy format (zurik <= 1.0.5): base64( salt(16) | iv(16) | tag(16) | ciphertext ), default scrypt params.
-async function decryptV1(base64, password) {
-  const buffer = Buffer.from(base64, "base64");
-  if (buffer.length < 48) {
-    throw new ZurikError("E_CORRUPT", "Corrupted .zurik file");
-  }
-  const salt = buffer.subarray(0, 16);
-  const iv = buffer.subarray(16, 32);
-  const tag = buffer.subarray(32, 48);
-  const ciphertext = buffer.subarray(48);
-
-  const key = await deriveKey(password, salt, { logN: 14, r: 8, p: 1 });
-  const decipher = crypto.createDecipheriv(ALGO, key, iv);
-  decipher.setAuthTag(tag);
-  return finish(decipher, ciphertext);
-}
-
-function finish(decipher, ciphertext) {
+export function open(key, header, filePath, data) {
+  const buffer = Buffer.from(data, "base64");
   try {
-    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    const decipher = crypto.createDecipheriv(ALGO, key, buffer.subarray(0, IV_LENGTH));
+    decipher.setAAD(aad(header, filePath));
+    decipher.setAuthTag(buffer.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH));
+    const plain = Buffer.concat([decipher.update(buffer.subarray(IV_LENGTH + TAG_LENGTH)), decipher.final()]);
+    return { mode: plain.readUInt16BE(0) & 0o777, content: plain.subarray(2) };
   } catch {
-    throw new ZurikError("E_WRONG_PASSWORD", "Decryption failed: wrong password or corrupted .zurik file");
+    throw new ZurikError("E_WRONG_PASSWORD", `Cannot decrypt ${filePath}: wrong password or the .zurik file was modified`, {
+      path: filePath,
+    });
   }
 }

package/lib/decrypt.js

@@ -1,12 +1,15 @@
 import fs from "fs";
 import path from "path";
 import { ZurikError } from "./errors.js";
-import { compareLocal, readBundle } from "./bundle.js";
+import { BUNDLE_FILE, compareLocal, openBundle, readBundle } from "./bundle.js";
 
 const ACTION = { missing: "created", same: "unchanged", different: "updated" };
 
 export default async function decryptFiles({ root, password, force = false, dryRun = false }) {
-  const entries = (await readBundle(root, password)).map(entry => ({
+  const bundle = readBundle(root);
+  if (bundle === null) throw new ZurikError("E_NO_BUNDLE", `${BUNDLE_FILE} not found in ${root}`);
+
+  const entries = (await openBundle(bundle, password)).map(entry => ({
     ...entry,
     action: ACTION[compareLocal(root, entry.path, entry.content)],
   }));

package/lib/encrypt.js

@@ -1,11 +1,10 @@
 import fs from "fs";
 import path from "path";
-import { encryptData, MIN_PASSWORD_LENGTH } from "./crypto.js";
+import { deriveKey, newHeader, open, seal, MIN_PASSWORD_LENGTH } from "./crypto.js";
 import { ZurikError } from "./errors.js";
-import { BUNDLE_FILE, LIST_FILE, readFileList } from "./bundle.js";
+import { BUNDLE_FILE, readBundle, writeBundle } from "./bundle.js";
 
-export default async function encryptFiles({ root, password, dryRun = false }) {
-  // Only enforced when encrypting, so bundles made with shorter passwords still decrypt.
+export default async function encryptFiles({ root, password, rekey = false, dryRun = false }) {
   if ([...password].length < MIN_PASSWORD_LENGTH) {
     throw new ZurikError(
       "E_WEAK_PASSWORD",
@@ -14,44 +13,47 @@ export default async function encryptFiles({ root, password, dryRun = false }) {
     );
   }
 
-  const fileList = readFileList(root);
-  if (fileList === null) {
-    throw new ZurikError("E_NO_LIST", `${LIST_FILE} not found in ${root}`);
-  }
-  if (fileList.length === 0) {
-    throw new ZurikError("E_EMPTY_LIST", `No files listed in ${LIST_FILE}`);
-  }
+  const bundle = readBundle(root);
+  if (bundle === null) throw new ZurikError("E_NO_BUNDLE", `${BUNDLE_FILE} not found in ${root} (run 'zurik init')`);
+  if (bundle.files.length === 0) throw new ZurikError("E_EMPTY_LIST", `No files listed in ${BUNDLE_FILE}`);
 
-  // Refuse to write a partial bundle: it would silently overwrite secrets in the existing .zurik.
-  const missing = fileList.filter(f => !fs.existsSync(path.join(root, f)));
+  // Refuse to write a partial bundle: it would silently drop secrets from .zurik.
+  const missing = bundle.files.map(f => f.path).filter(p => !fs.existsSync(path.join(root, p)));
   if (missing.length > 0) {
     throw new ZurikError(
       "E_MISSING_FILES",
-      `Missing files listed in ${LIST_FILE} (run 'zurik decrypt' first?):\n  ${missing.join("\n  ")}`,
+      `Missing files listed in ${BUNDLE_FILE} (run 'zurik decrypt' first?):\n  ${missing.join("\n  ")}`,
       { files: missing }
     );
   }
 
-  // `modes` is optional so bundles stay readable by older zurik versions.
-  const bundle = { version: 1, files: {}, modes: {} };
+  // Keeping the header (salt) lets unchanged files keep their exact block, so git diffs and merges per file.
+  const header = bundle.header && !rekey ? bundle.header : newHeader();
+  const key = await deriveKey(header, password);
 
-  for (const filePath of fileList) {
-    const abs = path.join(root, filePath);
-    bundle.files[filePath] = fs.readFileSync(abs).toString("base64");
-    bundle.modes[filePath] = fs.statSync(abs).mode & 0o777;
-  }
+  const files = bundle.files.map(({ path: p, data }) => {
+    const abs = path.join(root, p);
+    const content = fs.readFileSync(abs);
+    // ponytail: a permission-only change keeps the old block (and mode); compare modes too if that matters.
+    if (data && header === bundle.header && unseal(key, header, p, data).content.equals(content)) {
+      return { path: p, data, action: "unchanged" };
+    }
+    return { path: p, data: seal(key, header, p, { content, mode: fs.statSync(abs).mode }), action: "encrypted" };
+  });
 
-  const encrypted = await encryptData(JSON.stringify(bundle), password);
-  const gitignoreAdded = updateGitignore(root, fileList, dryRun);
+  const gitignoreAdded = updateGitignore(root, files.map(f => f.path), dryRun);
+  if (!dryRun) writeBundle(root, { header, files });
 
-  if (!dryRun) {
-    fs.writeFileSync(path.join(root, BUNDLE_FILE), encrypted);
-  }
+  return { files: files.map(({ path, action }) => ({ path, action })), gitignoreAdded };
+}
 
-  return {
-    files: fileList.map(p => ({ path: p, action: "encrypted" })),
-    gitignoreAdded,
-  };
+function unseal(key, header, p, data) {
+  try {
+    return open(key, header, p, data);
+  } catch (err) {
+    err.message += ". To change the password, rerun with --rekey.";
+    throw err;
+  }
 }
 
 // Appends listed files that .gitignore doesn't already contain as a whole line. Returns what was (or would be) added.

package/lib/errors.js

@@ -3,13 +3,13 @@ export const ERROR_CODES = {
   E_USAGE: "Invalid command line arguments",
   E_NO_PASSWORD: "No password was provided",
   E_WEAK_PASSWORD: "Password is too short to encrypt with",
-  E_WRONG_PASSWORD: "Wrong password, or the bundle was modified",
+  E_WRONG_PASSWORD: "Wrong password, or the bundle was modified (details.path)",
   E_CORRUPT: "The .zurik file is not a valid bundle",
-  E_NOT_FOUND: "No .gitencrypt / .zurik found in this directory or any parent",
-  E_NO_LIST: ".gitencrypt is missing",
-  E_EMPTY_LIST: ".gitencrypt lists no files",
+  E_OLD_FORMAT: ".zurik was written by zurik 2.x or earlier; decrypt it with `npx zurik@2 decrypt` and set it up again",
+  E_NOT_FOUND: "No .zurik found in this directory or any parent (run `zurik init`)",
+  E_EMPTY_LIST: ".zurik lists no files",
   E_NO_BUNDLE: ".zurik is missing",
-  E_MISSING_FILES: "Files listed in .gitencrypt do not exist (details.files)",
+  E_MISSING_FILES: "Files listed in .zurik do not exist locally (details.files)",
   E_WOULD_OVERWRITE: "Local files differ from the bundle; rerun with --force (details.files)",
   E_UNSAFE_PATH: "A path is absolute or outside the project (details.path)",
   E_INTERNAL: "Unexpected internal error",

package/lib/index.js

@@ -1,33 +1,23 @@
 // Programmatic API. Every function returns a plain result object and throws ZurikError
 // (with a stable `code`) on failure. Nothing is printed and process.cwd() is never changed.
 import path from "path";
+import initList from "./init.js";
 import encryptFiles from "./encrypt.js";
 import decryptFiles from "./decrypt.js";
 import statusFiles from "./status.js";
-import initList from "./init.js";
-import { BUNDLE_FILE, LIST_FILE } from "./bundle.js";
+import { BUNDLE_FILE } from "./bundle.js";
 import { ZurikError, ERROR_CODES } from "./errors.js";
 import { findProjectRoot } from "./paths.js";
 import { MIN_PASSWORD_LENGTH } from "./crypto.js";
 
 export { ZurikError, ERROR_CODES, MIN_PASSWORD_LENGTH };
 
-const MARKERS = {
-  encrypt: [LIST_FILE],
-  decrypt: [BUNDLE_FILE],
-  status: [LIST_FILE, BUNDLE_FILE],
-};
-
-// `root` is used as-is; otherwise the nearest parent of `cwd` holding the command's marker file.
-export function resolveRoot(command, { root, cwd = process.cwd() } = {}) {
+// `root` is used as-is; otherwise the nearest parent of `cwd` holding .zurik.
+function resolveRoot({ root, cwd = process.cwd() }) {
   if (root) return path.resolve(root);
-  const markers = MARKERS[command];
-  const found = findProjectRoot(markers, cwd);
+  const found = findProjectRoot([BUNDLE_FILE], cwd);
   if (!found) {
-    throw new ZurikError(
-      "E_NOT_FOUND",
-      `${markers.join(" or ")} not found in ${path.resolve(cwd)} or any parent directory`
-    );
+    throw new ZurikError("E_NOT_FOUND", `${BUNDLE_FILE} not found in ${path.resolve(cwd)} or any parent directory (run 'zurik init')`);
   }
   return found;
 }
@@ -38,10 +28,19 @@ function requirePassword(password) {
   }
 }
 
-/** Encrypt the files listed in .gitencrypt into .zurik. Options: { password, root?, cwd?, dryRun? } */
+/** Add .env files (or `files`) to .zurik, creating it if missing. No password needed.
+ *  Options: { root?, cwd?, files?, dryRun? }. Root: `root`, else the nearest parent with .zurik or .git, else `cwd`. */
+export async function init(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const root = options.root ? path.resolve(options.root) : findProjectRoot([BUNDLE_FILE, ".git"], cwd) ?? path.resolve(cwd);
+  const dryRun = Boolean(options.dryRun);
+  return { command: "init", root, dryRun, ...initList({ ...options, root, dryRun }) };
+}
+
+/** Encrypt the files listed in .zurik. Options: { password, root?, cwd?, rekey?, dryRun? } */
 export async function encrypt(options = {}) {
   requirePassword(options.password);
-  const root = resolveRoot("encrypt", options);
+  const root = resolveRoot(options);
   const dryRun = Boolean(options.dryRun);
   return { command: "encrypt", root, dryRun, ...(await encryptFiles({ ...options, root, dryRun })) };
 }
@@ -49,22 +48,13 @@ export async function encrypt(options = {}) {
 /** Decrypt .zurik into the working tree. Options: { password, root?, cwd?, force?, dryRun? } */
 export async function decrypt(options = {}) {
   requirePassword(options.password);
-  const root = resolveRoot("decrypt", options);
+  const root = resolveRoot(options);
   const dryRun = Boolean(options.dryRun);
   return { command: "decrypt", root, dryRun, ...(await decryptFiles({ ...options, root, dryRun })) };
 }
 
-/** Compare .gitencrypt, .zurik and local files. The password is only needed when .zurik exists. */
+/** Compare .zurik with local files. The password is only needed once something is encrypted. */
 export async function status(options = {}) {
-  const root = resolveRoot("status", options);
+  const root = resolveRoot(options);
   return { command: "status", root, ...(await statusFiles({ ...options, root })) };
 }
-
-/** Add .env files (or `files`) to .gitencrypt, creating it if missing. No password needed.
- *  Options: { root?, cwd?, files?, dryRun? }. Root: `root`, else the nearest parent with .gitencrypt or .git, else `cwd`. */
-export async function init(options = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  const root = options.root ? path.resolve(options.root) : findProjectRoot([LIST_FILE, ".git"], cwd) ?? path.resolve(cwd);
-  const dryRun = Boolean(options.dryRun);
-  return { command: "init", root, dryRun, ...initList({ ...options, root, dryRun }) };
-}

package/lib/init.js

@@ -1,14 +1,12 @@
 import fs from "fs";
 import path from "path";
-import { LIST_FILE, readFileList } from "./bundle.js";
+import { readBundle, writeBundle } from "./bundle.js";
 import { safeRelativePath } from "./paths.js";
 
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
 const ENV_FILE = /^\.env(\..+)?$|\.env$/; // .env, .env.local, prod.env
 const TEMPLATE = /\.(example|sample|template|dist)$/i; // meant to be committed, not secret
 
-const HEADER = "# Files to encrypt into .zurik with `zurik encrypt`, one path per line.\n";
-
 // .env-style files under `root`, as sorted "/"-separated relative paths.
 export function findEnvFiles(root) {
   const found = [];
@@ -32,24 +30,24 @@ export function findEnvFiles(root) {
   return found.sort();
 }
 
-// Adds `files` (default: every .env file found) to .gitencrypt, creating it if needed.
+// Adds `files` (default: every .env file found) to .zurik as not-yet-encrypted sections, creating it if needed.
 export default function initList({ root, files, dryRun = false }) {
-  const listed = readFileList(root);
-  const already = new Set(listed ?? []);
+  const bundle = readBundle(root);
+  const already = new Set((bundle?.files ?? []).map(f => f.path));
   const found = findEnvFiles(root);
 
   const chosen = new Set(files ? files.map(f => safeRelativePath(f, root)) : found);
   const added = [...chosen].filter(f => !already.has(f));
 
-  if (!dryRun && (listed === null || added.length > 0)) {
-    const listPath = path.join(root, LIST_FILE);
-    const text = listed === null ? HEADER : fs.readFileSync(listPath, "utf8");
-    const sep = text && !text.endsWith("\n") ? "\n" : "";
-    fs.writeFileSync(listPath, text + sep + added.map(f => f + "\n").join(""));
+  if (!dryRun && (bundle === null || added.length > 0)) {
+    writeBundle(root, {
+      header: bundle?.header ?? null,
+      files: [...(bundle?.files ?? []), ...added.map(p => ({ path: p, data: "" }))],
+    });
   }
 
   return {
-    created: listed === null,
+    created: bundle === null,
     files: [
       ...found.filter(f => already.has(f)).map(p => ({ path: p, action: "already-listed" })),
       ...added.map(p => ({ path: p, action: "added" })),

package/lib/paths.js

@@ -15,7 +15,7 @@ export function findProjectRoot(markers, start = process.cwd()) {
 
 // Normalizes a bundle path and ensures it stays inside `root`. Returns a "/"-separated relative path.
 export function safeRelativePath(filePath, root) {
-  if (typeof filePath !== "string" || filePath.length === 0 || path.isAbsolute(filePath)) {
+  if (typeof filePath !== "string" || filePath.length === 0 || path.isAbsolute(filePath) || /[\r\n]/.test(filePath)) {
     throw new ZurikError("E_UNSAFE_PATH", `Refusing unsafe path: ${filePath}`, { path: filePath });
   }
 

package/lib/status.js

@@ -1,39 +1,30 @@
 import fs from "fs";
 import path from "path";
-import { BUNDLE_FILE, compareLocal, readBundle, readFileList } from "./bundle.js";
+import { BUNDLE_FILE, compareLocal, openBundle, readBundle } from "./bundle.js";
 import { ZurikError } from "./errors.js";
 
-// Per-file state, comparing .gitencrypt, .zurik and the working tree. Never reveals file contents.
+// Per-file state, comparing .zurik with the working tree. Never reveals file contents.
 //   in-sync          local file matches the bundle
 //   modified         local file differs from the bundle  -> encrypt to save it, or decrypt --force to discard
 //   missing-locally  in the bundle, not on disk          -> decrypt
-//   not-in-bundle    listed and on disk, not in bundle   -> encrypt
-//   missing          listed, but neither on disk nor in the bundle
-// `listed` is false for files in the bundle that were removed from .gitencrypt (the next encrypt drops them).
+//   not-in-bundle    listed and on disk, not encrypted yet -> encrypt
+//   missing          listed, but neither on disk nor encrypted
+// The password is only needed once something is encrypted.
 export default async function status({ root, password }) {
-  const listed = new Set(readFileList(root) ?? []);
-  const bundleExists = fs.existsSync(path.join(root, BUNDLE_FILE));
-  if (bundleExists && (typeof password !== "string" || password.length === 0)) {
+  const bundle = readBundle(root);
+  if (bundle === null) throw new ZurikError("E_NO_BUNDLE", `${BUNDLE_FILE} not found in ${root}`);
+  if (bundle.files.some(f => f.data) && (typeof password !== "string" || password.length === 0)) {
     throw new ZurikError("E_NO_PASSWORD", `A password is required to compare against ${BUNDLE_FILE}`);
   }
-  const bundle = bundleExists ? await readBundle(root, password) : [];
-  const inBundle = new Map(bundle.map(e => [e.path, e.content]));
+  const opened = new Map((await openBundle(bundle, password)).map(e => [e.path, e.content]));
 
   const STATE = { missing: "missing-locally", same: "in-sync", different: "modified" };
-  const paths = [...new Set([...listed, ...inBundle.keys()])].sort();
+  const files = bundle.files.map(({ path: p }) => ({
+    path: p,
+    state: opened.has(p)
+      ? STATE[compareLocal(root, p, opened.get(p))]
+      : fs.existsSync(path.join(root, p)) ? "not-in-bundle" : "missing",
+  }));
 
-  const files = paths.map(p => {
-    const state = inBundle.has(p)
-      ? STATE[compareLocal(root, p, inBundle.get(p))]
-      : fs.existsSync(path.join(root, p))
-        ? "not-in-bundle"
-        : "missing";
-    return { path: p, state, listed: listed.has(p) };
-  });
-
-  return {
-    bundleExists,
-    inSync: files.length > 0 && files.every(f => f.state === "in-sync" && f.listed),
-    files,
-  };
+  return { inSync: files.length > 0 && files.every(f => f.state === "in-sync"), files };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zurik",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "CLI tool for encrypting and decrypting sensitive project files into a single .zurik bundle.",
   "type": "module",
   "main": "./lib/index.js",

package/readme.md

@@ -1,11 +1,11 @@
 # zurik
 
 A Node.js CLI tool for encrypting and decrypting sensitive project files.
-It collects file paths from `.gitencrypt`, bundles them into a single `.zurik` file, and decrypts them when needed.
+It encrypts your secret files into a single `.zurik` file that you commit, and decrypts them when needed.
 
 ## Features
 
-- Encrypt multiple files into a **single** `.zurik` bundle
+- Encrypt multiple files into a **single** `.zurik` file, one section per file, so git diffs and merges each secret separately
 - AES-256-GCM authenticated encryption with a scrypt-derived key
 - Automatically appends sensitive files to `.gitignore` when encrypting
 - Preserves file permissions; never overwrites changed local files without `--force`
@@ -61,30 +61,25 @@ zurik never prompts when stdin is not a terminal, or with `--json`, `--no-input`
 npx zurik init
 ```
 
-`init` finds the `.env` files in your project (`.env`, `.env.local`, `prod.env`, ...; skipping `node_modules` and templates like `.env.example`) and lists them with all of them selected. Untick any you don't want (space toggles, enter confirms) and they are added to `.gitencrypt`, which is created if it doesn't exist. Run it again any time to pick up new `.env` files; paths already listed are left alone. It needs no password.
+`init` finds the `.env` files in your project (`.env`, `.env.local`, `prod.env`, ...; skipping `node_modules` and templates like `.env.example`) and lists them with all of them selected. Untick any you don't want (space toggles, enter confirms) and they are listed in `.zurik`, which is created if it doesn't exist. Run it again any time to pick up new `.env` files; files already listed are left alone. It needs no password.
 
 Outside a terminal (`--json`, `--no-input`, `$CI` or piped stdin) it adds every file found without asking. Add `--dry-run` to only see what it would do.
 
-### Encrypt files
+To encrypt other files, add a `--- <path>` line for each to `.zurik` (paths must be inside the project). To stop encrypting a file, delete its section.
 
-1. Create a `.gitencrypt` file in the root of your project (or run `zurik init`).
-2. Add the paths of the files you want to encrypt, one per line. Lines starting with `#` are ignored, and paths must be inside the project.
+### Encrypt files
 
-   ```txt
-   # secrets for local development
-   src/config.json
-   src/secret.txt
-   ```
+```sh
+npx zurik encrypt
+```
 
-3. Run:
+Every file listed in `.zurik` is encrypted into its section, and any that are not already in `.gitignore` are appended to it. Commit `.zurik`.
 
-   ```sh
-   npx zurik encrypt
-   ```
+Files that haven't changed keep their exact encrypted text, so a commit only touches the sections of the secrets that changed, and two people changing different secrets merge without a conflict. If two people change the *same* secret, resolve the conflict by keeping one side and running `zurik encrypt` again.
 
-The files are encrypted into `.zurik`, and any that are not already listed in `.gitignore` are appended to it. Commit `.zurik` and `.gitencrypt`.
+Every listed file must exist. If any is missing, nothing is written, so secrets are never dropped from `.zurik`. On a fresh clone, run `zurik decrypt` first.
 
-Every listed file must exist. If any is missing, nothing is written, so an existing `.zurik` is never overwritten with a partial bundle. On a fresh clone, run `zurik decrypt` first.
+To change the password, run `zurik encrypt --rekey` with the new one; every file is re-encrypted. Without `--rekey`, encrypting with a different password than the one `.zurik` uses fails, so a typo can't lock the team out.
 
 ### Decrypt files
 
@@ -100,11 +95,11 @@ Files are restored to their original paths with their original permissions. If a
 npx zurik status
 ```
 
-Shows, for every file, whether it is `in-sync`, `modified`, `missing-locally`, `not-in-bundle` or `missing`, without writing anything or printing contents. The password is only needed once `.zurik` exists.
+Shows, for every file, whether it is `in-sync`, `modified`, `missing-locally`, `not-in-bundle` (listed, not encrypted yet) or `missing`, without writing anything or printing contents. The password is only needed once something is encrypted.
 
 Add `--dry-run` (`-n`) to `encrypt` or `decrypt` to see what would happen without writing anything.
 
-You can run zurik from any subdirectory: it uses the nearest parent directory containing `.gitencrypt` (encrypt), `.zurik` (decrypt) or either (status). `--cwd <dir>` runs it against another directory.
+You can run zurik from any subdirectory: it uses the nearest parent directory containing `.zurik`. `--cwd <dir>` runs it against another directory.
 
 The short flags from earlier versions still work: `-e` (encrypt), `-d` (decrypt), `-s` (status).
 
@@ -122,7 +117,7 @@ mkdir -p .claude/skills/zurik && npx zurik skill > .claude/skills/zurik/SKILL.md
 For other agents, add the output to `AGENTS.md`, or add this line:
 
 ```md
-Secrets are managed with zurik (.gitencrypt / .zurik). Run `npx zurik skill` for instructions; never read or print secret files or the password.
+Secrets are managed with zurik (.zurik). Run `npx zurik skill` for instructions; never read or print secret files or the password.
 ```
 
 **Provide the password** through `ZURIK_PASSWORD` or `ZURIK_PASSWORD_FILE` in the agent's environment, never in the prompt.
@@ -131,8 +126,8 @@ Secrets are managed with zurik (.gitencrypt / .zurik). Run `npx zurik skill` for
 
 ```sh
 $ npx zurik status --json
-{"ok":true,"command":"status","root":"/repo","bundleExists":true,"inSync":false,
- "files":[{"path":".env","state":"modified","listed":true}]}
+{"ok":true,"command":"status","root":"/repo","inSync":false,
+ "files":[{"path":".env","state":"modified"}]}
 
 $ npx zurik decrypt --json
 {"ok":false,"error":{"code":"E_WOULD_OVERWRITE","message":"...","details":{"files":[".env"]}}}
@@ -156,15 +151,41 @@ if (!s.inSync) {
 }
 ```
 
-`init({ cwd, files, dryRun })` adds `files` (default: every `.env` file found) to `.gitencrypt` and needs no password.
+`init({ cwd, files, dryRun })` lists `files` (default: every `.env` file found) in `.zurik` and needs no password.
 
-Options: `password`, `cwd` (search for the project root from here) or `root` (use exactly), `force` and `dryRun`.
+Options: `password`, `cwd` (search for the project root from here) or `root` (use exactly), `force`, `rekey` and `dryRun`.
 
-## Bundle format
+## File format
 
-`.zurik` is a text file: `zurik2:` followed by base64 of `logN | r | p | salt (16) | iv (12) | tag (16) | ciphertext`. The scrypt parameters are authenticated as AES-GCM additional data, so they cannot be altered to weaken the key.
+`.zurik` is a text file with a header line and one section per file:
+
+```txt
+zurik3 scrypt logN=17 r=8 p=1 salt=<base64>
+
+--- .env
+<base64 of iv (12) | tag (16) | ciphertext>
+
+--- api/.env.production
+<base64 ...>
+```
+
+The key is derived once from the password with the scrypt parameters and salt in the header. Each file is encrypted separately with AES-256-GCM; its plaintext is its permission bits followed by its content. The header line and the file's path are authenticated as additional data, so the scrypt parameters can't be weakened and a section can't be moved to another path. A section with no data line is listed but not encrypted yet.
+
+Because files are encrypted separately, anyone who can read `.zurik` can see each file's approximate size and which file changed in each commit (the paths are visible anyway, as they are in `.gitignore`).
+
+## Upgrading from zurik 2.x
+
+zurik 3 uses a new format and no longer reads `.zurik` files from 2.x or `.gitencrypt`. To migrate a project:
+
+```sh
+npx zurik@2 decrypt      # restore the files with the old version
+rm .zurik                # keep .gitencrypt for now: it shows which files to list
+npx zurik init           # lists the .env files; add a "--- <path>" line for any others
+npx zurik encrypt
+git rm .gitencrypt
+```
 
-Bundles written by zurik 1.0.5 and earlier (no `zurik2:` prefix) still decrypt, including those with passwords shorter than 16 characters. The next `zurik encrypt` rewrites them in the new format, and at that point the password must meet the minimum length.
+Everyone on the team needs zurik 3 after that; zurik 2.x can't read the new file.
 
 ## Development
 

package/skills/zurik/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: zurik
-description: Encrypt, decrypt and check project secrets (.env files, keys, config) that are stored in a .zurik bundle and listed in .gitencrypt. Use whenever a repo contains .zurik or .gitencrypt, when secret files are missing after a clone, when the user asks to encrypt/commit/share/restore secrets, or before editing or committing a file listed in .gitencrypt. Prefer it over reading, copying, printing or hand-encrypting secret files.
+description: Encrypt, decrypt and check project secrets (.env files, keys, config) that are stored in a .zurik file. Use whenever a repo contains .zurik, when secret files are missing after a clone, when the user asks to encrypt/commit/share/restore secrets, or before editing or committing a file listed in .zurik. Prefer it over reading, copying, printing or hand-encrypting secret files.
 ---
 
 # zurik
 
-zurik keeps a project's secret files encrypted in one committed file, `.zurik`. The plaintext files are listed in `.gitencrypt` and are git-ignored. zurik never prints file contents, so you can manage secrets without them entering your context.
+zurik keeps a project's secret files encrypted in one committed file, `.zurik`, with one `--- <path>` section per file. The plaintext files are git-ignored. zurik never prints file contents, so you can manage secrets without them entering your context.
 
 Run it with `npx zurik` (or `zurik` if it's installed). Always pass `--json` and branch on `ok` / `error.code`, never on message text.
 
@@ -13,14 +13,14 @@ Run it with `npx zurik` (or `zurik` if it's installed). Always pass `--json` and
 
 | Goal | Command |
 |---|---|
-| Set up a repo without `.gitencrypt` (adds every `.env` file found; no password) | `npx zurik init --dry-run --json`, confirm the list with the user, then `npx zurik init --json` |
+| Set up a repo without `.zurik` (lists every `.env` file found; no password) | `npx zurik init --dry-run --json`, confirm the list with the user, then `npx zurik init --json` |
 | See what's out of sync (safe, read-only) | `npx zurik status --json` |
 | Restore secrets after a clone | `npx zurik decrypt --json` |
 | Save changes to secret files into `.zurik` | `npx zurik encrypt --json` |
 | Preview without writing anything | add `--dry-run` |
 | Machine-readable spec of all options and codes | `npx zurik help --json` |
 
-`--cwd <dir>` runs against another directory. zurik uses the nearest parent directory containing `.gitencrypt` / `.zurik`.
+`--cwd <dir>` runs against another directory. zurik uses the nearest parent directory containing `.zurik`.
 
 ## Password: never put it in your context
 
@@ -31,22 +31,23 @@ Run it with `npx zurik` (or `zurik` if it's installed). Always pass `--json` and
 
 ## Workflow
 
-1. `status --json` first. States: `in-sync`, `modified` (local differs from bundle), `missing-locally` (run decrypt), `not-in-bundle` (run encrypt), `missing` (listed but absent everywhere). `listed: false` means it's in the bundle but was removed from `.gitencrypt`.
+1. `status --json` first. States: `in-sync`, `modified` (local differs from bundle), `missing-locally` (run decrypt), `not-in-bundle` (listed, not encrypted yet: run encrypt), `missing` (listed but absent everywhere).
 2. After a clone or when files are `missing-locally`: `decrypt --json`.
-3. After you or the user changed a secret file: `encrypt --json`, then commit `.zurik` (and `.gitencrypt` / `.gitignore` if they changed). Never commit the plaintext files.
-4. To protect a new secret file: append its path to `.gitencrypt`, then `encrypt --json`. zurik adds it to `.gitignore` for you.
+3. After you or the user changed a secret file: `encrypt --json`, then commit `.zurik` (and `.gitignore` if it changed). Never commit the plaintext files.
+4. To protect a new secret file: append a `--- <path>` line to `.zurik`, then `encrypt --json`. zurik adds it to `.gitignore` for you.
 
 ## Errors
 
 | `error.code` | What to do |
 |---|---|
 | `E_NO_PASSWORD` | Ask the user to provide the password via the environment (see above). |
-| `E_WRONG_PASSWORD` | Wrong password or tampered bundle. Tell the user; don't retry with guesses. |
+| `E_WRONG_PASSWORD` | Wrong password or tampered `.zurik`. Tell the user; don't retry with guesses, and never use `--rekey` unless the user asks to change the password. |
 | `E_WOULD_OVERWRITE` | `error.details.files` have local changes. **Ask the user** before rerunning with `--force`; it discards those changes. If they should be kept, run `encrypt` instead. |
-| `E_MISSING_FILES` | `error.details.files` are listed but absent. Usually run `decrypt` first, or remove them from `.gitencrypt` if they're obsolete. |
+| `E_MISSING_FILES` | `error.details.files` are listed but absent. Usually run `decrypt` first, or remove their sections from `.zurik` if they're obsolete. |
 | `E_WEAK_PASSWORD` | Encrypting needs 16+ characters. The user must choose a longer password. |
-| `E_NOT_FOUND`, `E_NO_LIST`, `E_NO_BUNDLE`, `E_EMPTY_LIST` | Nothing to work on at this location; check `--cwd` or set up `.gitencrypt`. |
-| `E_UNSAFE_PATH` | A path is absolute or outside the project. Fix `.gitencrypt`; for a bundle, treat it as suspicious and tell the user. |
+| `E_NOT_FOUND`, `E_NO_BUNDLE`, `E_EMPTY_LIST` | Nothing to work on at this location; check `--cwd`, or run `init` to set up `.zurik`. |
+| `E_OLD_FORMAT` | `.zurik` is from zurik 2.x. Tell the user; migrating needs `npx zurik@2 decrypt` and the password (see the readme). Don't delete `.zurik` yourself. |
+| `E_UNSAFE_PATH` | A path in `.zurik` is absolute or outside the project. If you added it, fix it; otherwise treat the file as suspicious and tell the user. |
 
 Exit codes: `0` success, `1` error, `2` usage error.
 
@@ -54,4 +55,4 @@ Exit codes: `0` success, `1` error, `2` usage error.
 
 - Don't `cat`, print, summarize or copy decrypted secret files unless the user explicitly asks to see them. Edit them in place when a task requires it.
 - Don't use `--force` without the user's go-ahead.
-- Don't delete `.zurik`, and don't remove entries from `.gitencrypt` unless asked.
+- Don't delete `.zurik`, and don't remove its sections unless asked.