@m2farhood-2/qapture 0.2.0

package/dist/bin/init.cjs

@@ -0,0 +1,1186 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/bin/init.ts
+var path7 = __toESM(require("path"), 1);
+var fs7 = __toESM(require("fs"), 1);
+var process2 = __toESM(require("process"), 1);
+
+// src/artifacts/SKILL.md
+var SKILL_default = "---\nname: qapture\ndescription: >\n  Activated when the user provides a `qa-notes-*.zip` file exported from\n  Qapture. Reads the preamble block in `notes.md` (project context, stack, run\n  commands, theme tokens, dev/test login credentials, red-zone coverage report,\n  and invariants), flags any uncovered RED risk zones before acting, then works\n  through each `## Point N` annotation (page, element selector, screenshot \u2192\n  locate code \u2192 make the change \u2192 verify by running the app). Finally grades\n  coverage against the red zones and reports.\n\n  **No AI is bundled in Qapture \u2014 YOU are the AI reading these artifacts.**\n  Qapture is a 100% client-side, keyless, network-free capture widget.\ntriggers:\n  - qa-notes-*.zip\n---\n\n# Qapture \u2014 Agent Skill\n\n> **Core principle:** Qapture ships zero AI. No model, no API keys, no network\n> calls. The CLI is a plain deterministic scaffolder. **You** \u2014 the coding agent\n> reading this skill \u2014 are the AI. The developer used Qapture to capture\n> annotated screenshots + notes from their live app; your job is to act on them.\n\n---\n\n## What Is Qapture?\n\nQapture is a drop-in in-browser widget (Shadow DOM, keyless, no telemetry).\nTesters annotate the live app: click an element or draw a region, add a note,\nand the widget captures a screenshot automatically. When done, they export a\n`qa-notes-*.zip`. That ZIP is the hand-off to you.\n\n---\n\n## ZIP Layout\n\n```\nqa-notes-<timestamp>.zip\n\u251C\u2500\u2500 notes.md          \u2190 ALWAYS read this first (see Step 1)\n\u2514\u2500\u2500 screenshots/\n    \u251C\u2500\u2500 point-1.png\n    \u251C\u2500\u2500 point-2.png\n    \u2514\u2500\u2500 ...\n```\n\n### `notes.md` structure\n\n```\n[PREAMBLE BLOCK]\n  Project name, one-liner, stack, run commands, theme tokens,\n  Login Context (dev/test credentials \u2014 see security note below),\n  Coverage Report (red/amber/green zone checklist),\n  Invariants, Additional Context.\n\n---NOTES---\n\n## Point 1\nPage: /some/path\nSelector: #some-element   (or [data-testid=\"foo\"] etc.)\nNote: the tester's free-text description of the issue / request\n\n## Point 2\n...\n```\n\n---\n\n## Step 1 \u2014 Read the Preamble First\n\nBefore touching any code, open `notes.md` and parse everything **above** the\n`---NOTES---` separator. Extract and internalize:\n\n| Section            | What to do                                                            |\n| ------------------ | --------------------------------------------------------------------- |\n| **Project / Stack** | Understand the framework, router, ORM, and any unusual constraints.  |\n| **Run Commands**   | Know how to start the dev server and seed the database.               |\n| **Theme Tokens**   | Understand the colour palette so you don't introduce style regressions.|\n| **Login Context**  | DEV/TEST/SEED credentials only. Use these to log in during verification. **Never log, forward, or commit these values.** |\n| **Coverage Report**| List of RED / AMBER / GREEN zones and whether they are covered.       |\n| **Invariants**     | Absolute rules you must never violate (e.g. \"prices \u2265 0\", \"checkout requires auth\"). |\n| **Conventions**    | Codebase naming, file organisation, import rules, validation approach. |\n\n---\n\n## Step 2 \u2014 Flag Uncovered RED Zones Before Acting\n\nAfter reading the preamble, check the Coverage Report for any RED zones that\nare **not yet covered** by an annotation in this ZIP.\n\nIf uncovered RED zones exist, **report them to the developer first**:\n\n```\n\u26A0\uFE0F  Uncovered RED zones detected:\n  \u2022 /checkout/payment \u2014 no annotation in this export\n  \u2022 /seller/payouts  \u2014 no annotation in this export\n\nThese are money/auth/irreversible flows. Do you want me to proceed with the\ncovered points only, or will you add annotations for the red zones first?\n```\n\nWait for developer confirmation before proceeding if any RED zone is uncovered.\n\n---\n\n## Step 3 \u2014 Act on Each Point\n\nFor each `## Point N` section in `notes.md`:\n\n### 3a. Read the annotation\n\n- **Page** \u2014 the route/URL where the issue was captured.\n- **Selector** \u2014 the CSS selector or aria identifier for the element.\n- **Note** \u2014 the tester's description of the problem or change request.\n\n### 3b. Open the screenshot\n\nLoad `screenshots/point-N.png` to visually confirm what the tester saw.\nThe screenshot is truth \u2014 if the selector doesn't resolve, the screenshot tells\nyou what element they meant.\n\n### 3c. Locate the code\n\nUse the selector priority chain below to find the relevant source:\n\n| Priority | Selector type                                      | Action                                              |\n| -------- | -------------------------------------------------- | --------------------------------------------------- |\n| 1        | `#some-id`                                         | `grep -r 'some-id'` in `src/`                       |\n| 2        | `[data-testid=\"foo\"]` / `[data-test]` / `[data-cy]` | grep for the attribute value                       |\n| 3        | `aria-label` on interactive elements               | grep for the label string                           |\n| 4        | `name` attribute on form fields                    | grep for `name=\"...\"` in the relevant form file     |\n| 5        | Structural (e.g. `.card:nth-of-type(2) > button`) | narrow by page route \u2192 component file \u2192 visual match with screenshot |\n| Fallback | Selector didn't resolve                            | Use the screenshot: identify the element visually, search by text content or component name |\n\nNarrow your search by the **Page** field to avoid editing the wrong route's code.\n\n### 3d. Make the change\n\n- Follow the project's **Conventions** (from the preamble).\n- Respect all **Invariants** \u2014 never violate them even if the annotation implies it.\n- If the change touches a RED zone (money / auth / irreversible state), add an\n  explicit comment: `// QA: red-zone change \u2014 reviewed <date>`.\n- Do **not** edit `qa.config.ts`, `qa.preamble.md`, or any qapture plugin files.\n\n---\n\n## Step 4 \u2014 Verify the Fix\n\n1. Run the app using the **Run Commands** from the preamble.\n2. Log in as the relevant role using **Login Context** credentials.\n   (These are DEV/TEST/SEED only \u2014 never use production credentials.)\n3. Navigate to the **Page** listed in the annotation.\n4. **Reproduce** the original issue to confirm it existed, then verify it is fixed.\n5. In the browser console, run `document.querySelector('<selector>')` to confirm\n   the element resolves as expected.\n6. Check adjacent paths for regressions, especially if the change is in a shared\n   component.\n\n---\n\n## Step 5 \u2014 Grade and Report\n\nAfter acting on all points, produce a short report:\n\n```markdown\n## Qapture \u2014 Changes Summary\n\n| Point | Page            | Change made                   | Verified | Risk  |\n| ----- | --------------- | ----------------------------- | -------- | ----- |\n| 1     | /products       | Fixed button label            | \u2713        | green |\n| 2     | /checkout       | Corrected total calculation   | \u2713        | red   |\n\n### Coverage vs Red Zones\n- [x] /checkout/payment \u2014 covered by Point 2\n- [ ] /seller/payouts  \u2014 NOT covered (flagged in Step 2)\n\n### Uncovered items\nNone (all annotated points addressed).\n```\n\n---\n\n## Risk Zone Reference\n\n| Risk    | Examples                                                          | Rule                                             |\n| ------- | ----------------------------------------------------------------- | ------------------------------------------------ |\n| **red** | Payment, checkout, auth, order state, refunds, payouts, user data | Never change without developer review + comment  |\n| **amber** | Cart, product listings, search, seller dashboard, inventory    | Change carefully; verify end-to-end              |\n| **green** | Static content, labels, colours, copy, tooltips, layout        | Change freely; quick smoke-test                  |\n\n---\n\n## Security Note\n\n- **Dev/test/seed credentials only.** The Login Context in `notes.md` contains\n  credentials from `.env.example` or seeder files \u2014 never from production.\n- **Never log, forward, store, or commit** Login Context values outside the\n  development environment.\n- **Never read** `.env`, `.env.local`, `.env.production`, or any `secrets/`\n  path. Qapture's CLI enforces this; you must too.\n- Qapture is **100% client-side** \u2014 it makes no network calls, holds no API\n  keys, and sends no data anywhere.\n- **Never push, publish, or deploy** changes without explicit human approval,\n  regardless of risk level.\n\n---\n\n## Common Pitfalls\n\n- **Don't assume selectors always resolve.** Selector strings may be stale if\n  the DOM changed after annotation. When in doubt, use the screenshot.\n- **Don't skip the preamble.** Acting without reading the invariants or run\n  commands is the most common source of broken fixes.\n- **Don't edit qapture config or plugin files** (`qa.config.ts`,\n  `qa.preamble.md`, `.claude/skills/qapture/`, `src/components/qa-overlay/`).\n- **Don't use production credentials** \u2014 ever.\n- **Don't push/publish without human approval** \u2014 always present the changes\n  for review first.\n- **Don't violate invariants** even if the annotation seems to imply it.\n  Surface the conflict to the developer instead.\n\n---\n\n_Qapture \u2014 https://github.com/mohammed-farhood/qapture_\n";
+
+// src/artifacts/AGENTS_SECTION.md
+var AGENTS_SECTION_default = '<!-- qa-studio-section -->\n\n## Qapture\n\nThis project uses **Qapture** \u2014 an in-browser QA capture widget that ships\n**zero AI** (no model, no API keys, no network calls). **You** are the AI.\n\n### When you receive a `qa-notes-*.zip`\n\n1. **Unzip** the file.\n2. **Read `notes.md` top-to-bottom**, starting with everything above the\n   `---NOTES---` separator:\n   - **Project context** \u2014 name, stack, run commands, conventions.\n   - **Theme tokens** \u2014 colour palette (respect these in any UI changes).\n   - **Login Context** \u2014 dev/test/seed credentials for the relevant roles.\n     _(DEV/TEST/SEED only \u2014 never commit, log, or forward these values.)_\n   - **Coverage Report** \u2014 red/amber/green zone checklist.\n   - **Invariants** \u2014 rules you must never violate (e.g. "prices \u2265 0",\n     "checkout requires auth").\n3. **Flag uncovered RED zones** before acting. RED = money / auth / irreversible\n   state. If any red zone has no annotation in this ZIP, report it and ask the\n   developer whether to proceed.\n4. **Act on each `## Point N`** annotation:\n   - **Page** + **Selector** + **Note** \u2192 locate the element in the source\n     (priority: `#id` \u2192 `[data-testid]` \u2192 `aria-label` \u2192 `name` \u2192 visual match\n     via the `screenshots/point-N.png`).\n   - Make the change following the project conventions and invariants.\n   - **Verify**: run the app, log in as the relevant role, navigate to the page,\n     confirm the fix.\n5. **Report** a summary table of changes, risk levels, and coverage status.\n\n### Full protocol\n\n`.claude/skills/qapture/SKILL.md` (always kept current by `qapture init`).\n\n### Rules\n\n- Never read `.env`, `.env.local`, `.env.production`, or any `secrets/` path.\n- Never edit `qa.config.ts`, `qa.preamble.md`, or any qapture plugin files.\n- Never push/publish/deploy without explicit human approval.\n- Dev/test/seed credentials only \u2014 never use or request production credentials.\n\n_Qapture \u2014 https://github.com/mohammed-farhood/qapture_\n\n<!-- /qa-studio-section -->\n';
+
+// src/bin/utils/args.ts
+function parseArgs(argv2) {
+  const [cmd, ...rest] = argv2;
+  if (cmd === "version" || cmd === "--version" || cmd === "-v" || cmd === "-V") {
+    return { command: "version", dir: process.cwd(), force: false };
+  }
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    return { command: "help", dir: process.cwd(), force: false };
+  }
+  if (cmd === "init") {
+    let dir = process.cwd();
+    let force = false;
+    for (const arg of rest) {
+      if (arg === "--force" || arg === "-f") {
+        force = true;
+      } else if (arg === "--no-force") {
+        force = false;
+      } else if (!arg.startsWith("-")) {
+        dir = arg;
+      }
+    }
+    return { command: "init", dir, force };
+  }
+  return { command: "help", dir: process.cwd(), force: false };
+}
+
+// src/bin/utils/writeIdempotent.ts
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+function writeIfAbsent(filePath, content, force) {
+  if (!force && fs.existsSync(filePath)) {
+    return "skipped";
+  }
+  ensureParentDir(filePath);
+  fs.writeFileSync(filePath, content, "utf8");
+  return "written";
+}
+function writeAlways(filePath, content) {
+  ensureParentDir(filePath);
+  fs.writeFileSync(filePath, content, "utf8");
+}
+function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// src/bin/utils/mergeAgentsMd.ts
+var fs2 = __toESM(require("fs"), 1);
+var SENTINEL_OPEN = "<!-- qa-studio-section -->";
+var SENTINEL_CLOSE = "<!-- /qa-studio-section -->";
+function mergeAgentsMd(agentsMdPath, sectionContent) {
+  if (!fs2.existsSync(agentsMdPath)) {
+    writeAlways(agentsMdPath, sectionContent.trimEnd() + "\n");
+    return "created";
+  }
+  const existing = fs2.readFileSync(agentsMdPath, "utf8");
+  const openIdx = existing.indexOf(SENTINEL_OPEN);
+  const closeIdx = existing.indexOf(SENTINEL_CLOSE);
+  if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
+    const before = existing.slice(0, openIdx);
+    const after = existing.slice(closeIdx + SENTINEL_CLOSE.length);
+    const updated = before.replace(/\n*$/, "\n") + sectionContent.trimEnd() + "\n" + after.replace(/^\n*/, "\n");
+    fs2.writeFileSync(agentsMdPath, updated, "utf8");
+    return "replaced";
+  }
+  const separator = existing.trimEnd().length === 0 ? "" : "\n\n";
+  fs2.writeFileSync(
+    agentsMdPath,
+    existing.trimEnd() + separator + sectionContent.trimEnd() + "\n",
+    "utf8"
+  );
+  return "appended";
+}
+
+// src/bin/detectors/detectRoutes.ts
+var path4 = __toESM(require("path"), 1);
+var fs4 = __toESM(require("fs"), 1);
+
+// src/bin/utils/walk.ts
+var fs3 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  ".cache",
+  "coverage",
+  ".nyc_output",
+  ".parcel-cache",
+  "__pycache__",
+  ".venv",
+  "vendor"
+]);
+function walk(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs3.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+      results.push(...walk(path2.join(dir, entry.name)));
+    } else if (entry.isFile()) {
+      results.push(path2.join(dir, entry.name));
+    }
+  }
+  return results;
+}
+function readFileSafe(filePath) {
+  try {
+    return fs3.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+function dirExists(dirPath) {
+  try {
+    return fs3.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// src/bin/utils/secretGuard.ts
+var path3 = __toESM(require("path"), 1);
+var BLOCKED_EXACT_BASENAMES = /* @__PURE__ */ new Set([
+  ".env",
+  ".env.local",
+  ".env.development",
+  ".env.test",
+  ".env.production",
+  ".env.staging",
+  ".env.ci",
+  ".env.preview",
+  ".env.override"
+]);
+var BLOCKED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".pem",
+  ".key",
+  ".pfx",
+  ".p12",
+  ".crt",
+  ".der",
+  ".p8",
+  ".jks",
+  ".keystore",
+  ".secret"
+]);
+var BLOCKED_BASENAME_PATTERNS = [
+  /^credentials?\./i,
+  // credentials.json, credential.yml, …
+  /^secrets?\./i,
+  // secrets.json, secret.yaml, …
+  /\.secret$/i,
+  // foo.secret
+  /^private_key/i,
+  // private_key.json (GCP service account)
+  /^service[-_]?account/i,
+  // service-account.json
+  /^keyfile/i,
+  // keyfile.json
+  /^\.netrc$/i,
+  /^\.pgpass$/i,
+  /^id_rsa/i,
+  // SSH private keys
+  /^id_ed25519/i,
+  /^id_ecdsa/i,
+  /^id_dsa/i
+];
+var BLOCKED_PATH_SEGMENTS = [
+  /[\\/]secrets?[\\/]/i,
+  /[\\/]\.secrets?[\\/]/i,
+  /[^\\/][\\/]private[\\/]/i,
+  /[\\/]certs?[\\/]/i,
+  /[\\/]certificates?[\\/]/i,
+  /[\\/]keys?[\\/]/i,
+  /[\\/]credentials?[\\/]/i
+];
+function assertSafeToRead(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const basename3 = path3.basename(filePath);
+  const ext = path3.extname(filePath).toLowerCase();
+  if (basename3 === ".env.example") return true;
+  if (/^\.env\.example(\.\w+)?$/.test(basename3)) return true;
+  if (BLOCKED_EXACT_BASENAMES.has(basename3)) return false;
+  if (/^\.env\./i.test(basename3) && !/^\.env\.example/i.test(basename3)) {
+    return false;
+  }
+  if (BLOCKED_EXTENSIONS.has(ext)) return false;
+  for (const pat of BLOCKED_BASENAME_PATTERNS) {
+    if (pat.test(basename3)) return false;
+  }
+  for (const pat of BLOCKED_PATH_SEGMENTS) {
+    if (pat.test(normalized)) return false;
+  }
+  return true;
+}
+
+// src/bin/detectors/detectRoutes.ts
+var LANE_COLORS = {
+  buyer: "#4f46e5",
+  // indigo
+  seller: "#7c3aed",
+  // violet
+  admin: "#dc2626"
+  // red
+};
+var LANE_META = [
+  { id: "buyer", en: "Buyer / Public", ar: "\u0627\u0644\u0645\u0634\u062A\u0631\u064A / \u0639\u0627\u0645" },
+  { id: "seller", en: "Seller", ar: "\u0627\u0644\u0628\u0627\u0626\u0639" },
+  { id: "admin", en: "Admin", ar: "\u0627\u0644\u0645\u0633\u0624\u0648\u0644" }
+];
+function makeStep(routePath) {
+  return {
+    path: routePath,
+    risk: "green",
+    what: { en: "TODO: describe what to test here", ar: "" }
+  };
+}
+function classifyPath(routePath) {
+  const p = routePath.toLowerCase();
+  if (/^\/(seller|store-owner|vendor)/.test(p)) return "seller";
+  if (/^\/(admin|dashboard|control-panel|backoffice|back-office|management|cms)/.test(p)) {
+    return "admin";
+  }
+  if (/^\/(login|signin|sign-in|signup|sign-up|register|auth|forgot-password|reset-password|verify|email-verification|oauth)/.test(p)) {
+    return "auth";
+  }
+  return "buyer";
+}
+function fileToNextPagesRoute(filePath, pagesDir) {
+  let rel = filePath.slice(pagesDir.length).replace(/\\/g, "/");
+  if (rel.startsWith("/")) rel = rel.slice(1);
+  rel = rel.replace(/\.(tsx?|jsx?|mdx?)$/, "");
+  if (rel === "index") return "/";
+  rel = rel.replace(/\/index$/, "");
+  if (/^_/.test(rel) || /^api(\/|$)/.test(rel)) return "";
+  rel = rel.replace(/\[\.\.\.([^\]]+)\]/g, "*").replace(/\[([^\]]+)\]/g, ":$1");
+  return "/" + rel;
+}
+var APP_PAGE_BASENAME = /^page\.(tsx?|jsx?)$/;
+function fileToAppRoute(filePath, appDir) {
+  if (!APP_PAGE_BASENAME.test(path4.basename(filePath))) return "";
+  let rel = path4.dirname(filePath).slice(appDir.length).replace(/\\/g, "/");
+  if (rel.startsWith("/")) rel = rel.slice(1);
+  rel = rel.replace(/\([^)]*\)\//g, "").replace(/\([^)]*\)$/, "");
+  rel = rel.replace(/\[\.\.\.([^\]]+)\]/g, "*").replace(/\[([^\]]+)\]/g, ":$1");
+  return "/" + (rel || "");
+}
+var SOURCE_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".vue", ".mjs", ".cjs"]);
+var RE_REACT_JSX = /<Route\b[^>]*\bpath=["']([^"']+)["']/g;
+var RE_REACT_OBJ = /\bpath:\s*["'](\/?[^"']+)["']/g;
+var RE_VUE_ROUTE = /\{\s*path:\s*["']([^"']+)["']/g;
+var RE_HTTP_ROUTE = /\bapp\.(?:get|post|put|patch|delete|all)\(["']([/][^"']+)["']/g;
+function grepSourceFile(filePath, addRoute) {
+  if (!SOURCE_EXTS.has(path4.extname(filePath).toLowerCase())) return;
+  if (!assertSafeToRead(filePath)) return;
+  const content = readFileSafe(filePath);
+  if (!content) return;
+  let m;
+  RE_REACT_JSX.lastIndex = 0;
+  while ((m = RE_REACT_JSX.exec(content)) !== null) addRoute(m[1]);
+  RE_REACT_OBJ.lastIndex = 0;
+  while ((m = RE_REACT_OBJ.exec(content)) !== null) {
+    if (m[1].startsWith("/") || m[1] === "*") addRoute(m[1]);
+  }
+  RE_VUE_ROUTE.lastIndex = 0;
+  while ((m = RE_VUE_ROUTE.exec(content)) !== null) addRoute(m[1]);
+  RE_HTTP_ROUTE.lastIndex = 0;
+  while ((m = RE_HTTP_ROUTE.exec(content)) !== null) addRoute(m[1]);
+}
+function detectRoutes(targetDir) {
+  const routes = /* @__PURE__ */ new Set();
+  const addRoute = (r) => {
+    const trimmed = r.trim();
+    if (trimmed && trimmed !== "*") routes.add(trimmed);
+  };
+  for (const dir of [
+    path4.join(targetDir, "pages"),
+    path4.join(targetDir, "src", "pages")
+  ]) {
+    if (!dirExists(dir)) continue;
+    for (const f of walk(dir)) {
+      if (assertSafeToRead(f)) {
+        const r = fileToNextPagesRoute(f, dir);
+        if (r) addRoute(r);
+      }
+    }
+  }
+  for (const dir of [
+    path4.join(targetDir, "app"),
+    path4.join(targetDir, "src", "app")
+  ]) {
+    if (!dirExists(dir)) continue;
+    for (const f of walk(dir)) {
+      if (assertSafeToRead(f)) {
+        const r = fileToAppRoute(f, dir);
+        if (r) addRoute(r);
+      }
+    }
+  }
+  const srcDir = path4.join(targetDir, "src");
+  if (dirExists(srcDir)) {
+    for (const f of walk(srcDir)) {
+      grepSourceFile(f, addRoute);
+    }
+  }
+  const rootCandidates = ["routes.ts", "routes.js", "router.ts", "router.js", "app.ts", "app.js"];
+  for (const name of rootCandidates) {
+    const f = path4.join(targetDir, name);
+    if (fs4.existsSync(f)) grepSourceFile(f, addRoute);
+  }
+  const buckets = { buyer: [], seller: [], admin: [] };
+  for (const route of Array.from(routes).sort()) {
+    const lane = classifyPath(route);
+    if (lane === "auth") continue;
+    buckets[lane].push(route);
+  }
+  const lanes = [];
+  for (const { id, en, ar } of LANE_META) {
+    const paths = buckets[id];
+    if (!paths || paths.length === 0) continue;
+    lanes.push({
+      id,
+      color: LANE_COLORS[id] ?? "#4f46e5",
+      role: { en, ar },
+      steps: paths.map(makeStep)
+    });
+  }
+  if (lanes.length === 0) {
+    lanes.push({
+      id: "buyer",
+      color: LANE_COLORS["buyer"],
+      role: { en: "Buyer / Public", ar: "\u0627\u0644\u0645\u0634\u062A\u0631\u064A / \u0639\u0627\u0645" },
+      steps: [makeStep("/")]
+    });
+  }
+  return lanes;
+}
+
+// src/bin/detectors/detectTheme.ts
+var path5 = __toESM(require("path"), 1);
+var fs5 = __toESM(require("fs"), 1);
+var PLACEHOLDER = "#REPLACE_ME";
+var KEY_ALIASES = [
+  {
+    key: "primaryDark",
+    patterns: [
+      /primary[-_]?dark/i,
+      /primary[-_]?(?:800|900|700|deep)/i,
+      /brand[-_]?dark/i
+    ]
+  },
+  {
+    key: "primary",
+    patterns: [
+      /^primary$/i,
+      /primary[-_]?(?:base|default|main|500|600)?$/i,
+      /^brand$/i,
+      /brand[-_]?(?:main|primary|base|default)?$/i
+    ]
+  },
+  {
+    key: "accentDark",
+    patterns: [
+      /accent[-_]?dark/i,
+      /accent[-_]?(?:700|800|900|deep)/i,
+      /secondary[-_]?dark/i
+    ]
+  },
+  {
+    key: "accent",
+    patterns: [
+      /^accent$/i,
+      /accent[-_]?(?:base|default|main|500|600)?$/i,
+      /^secondary$/i,
+      /secondary[-_]?(?:main|base|default)?$/i,
+      /^highlight$/i
+    ]
+  },
+  {
+    key: "sage",
+    patterns: [
+      /^sage$/i,
+      /^muted$/i,
+      /^neutral$/i,
+      /^subdued$/i,
+      /gray[-_]?500/i
+    ]
+  },
+  {
+    key: "cream",
+    patterns: [
+      /^cream$/i,
+      /^background[-_]?light$/i,
+      /^bg[-_]?light$/i,
+      /^off[-_]?white$/i,
+      /^paper$/i,
+      /^canvas$/i
+    ]
+  },
+  {
+    key: "mauve",
+    patterns: [
+      /^mauve$/i,
+      /^lavender$/i,
+      /^purple[-_]?light$/i,
+      /^lilac$/i,
+      /^periwinkle$/i
+    ]
+  },
+  {
+    key: "surface",
+    patterns: [
+      /^surface$/i,
+      /^card$/i,
+      /^panel$/i,
+      /^background$/i,
+      /^bg$/i
+    ]
+  },
+  {
+    key: "ink",
+    patterns: [
+      /^ink$/i,
+      /^text[-_]?(?:default|primary|base|main)?$/i,
+      /^foreground$/i,
+      /^content$/i,
+      /^copy$/i
+    ]
+  }
+];
+function resolveThemeKey(name) {
+  for (const { key, patterns } of KEY_ALIASES) {
+    for (const pat of patterns) {
+      if (pat.test(name)) return key;
+    }
+  }
+  return null;
+}
+var HEX_COLOR = /#[0-9a-fA-F]{3,8}\b/;
+function extractTailwindColors(content) {
+  const colors = /* @__PURE__ */ new Map();
+  const RE = /['"]?([\w-]+)['"]?\s*:\s*['"]?(#[0-9a-fA-F]{3,8})['"]?/g;
+  let m;
+  while ((m = RE.exec(content)) !== null) {
+    const [, name, hex] = m;
+    if (HEX_COLOR.test(hex)) {
+      colors.set(name.toLowerCase(), hex);
+    }
+  }
+  return colors;
+}
+function extractCssCustomProps(content) {
+  const colors = /* @__PURE__ */ new Map();
+  const RE = /--([\w-]+)\s*:\s*(#[0-9a-fA-F]{3,8})\b/g;
+  let m;
+  while ((m = RE.exec(content)) !== null) {
+    const [, varName, hex] = m;
+    if (!HEX_COLOR.test(hex)) continue;
+    const stripped = varName.replace(/^(?:color|colour|clr|c|qs|qa)[-_]/, "").toLowerCase();
+    if (!colors.has(stripped)) colors.set(stripped, hex);
+    if (!colors.has(varName.toLowerCase())) colors.set(varName.toLowerCase(), hex);
+  }
+  return colors;
+}
+var CSS_SEARCH_DIRS = [
+  "",
+  // root
+  "src",
+  "styles",
+  "css",
+  "src/styles",
+  "src/css",
+  "src/app",
+  "app",
+  "assets",
+  "assets/css",
+  "assets/styles",
+  "public"
+];
+function detectTheme(targetDir) {
+  const draft = {
+    primary: PLACEHOLDER,
+    primaryDark: PLACEHOLDER,
+    accent: PLACEHOLDER,
+    accentDark: PLACEHOLDER,
+    sage: PLACEHOLDER,
+    cream: PLACEHOLDER,
+    mauve: PLACEHOLDER,
+    surface: PLACEHOLDER,
+    ink: PLACEHOLDER
+  };
+  const allColors = /* @__PURE__ */ new Map();
+  const mergeColors = (extracted) => {
+    for (const [k, v] of extracted) {
+      if (!allColors.has(k)) allColors.set(k, v);
+    }
+  };
+  const tailwindNames = [
+    "tailwind.config.ts",
+    "tailwind.config.js",
+    "tailwind.config.cjs",
+    "tailwind.config.mjs"
+  ];
+  for (const name of tailwindNames) {
+    const filePath = path5.join(targetDir, name);
+    if (fs5.existsSync(filePath) && assertSafeToRead(filePath)) {
+      const content = readFileSafe(filePath);
+      if (content) mergeColors(extractTailwindColors(content));
+      break;
+    }
+  }
+  const CSS_EXTS = /\.(css|scss|sass|less|styl)$/i;
+  for (const rel of CSS_SEARCH_DIRS) {
+    const dirPath = rel ? path5.join(targetDir, rel) : targetDir;
+    if (!dirExists(dirPath)) continue;
+    const files = rel.includes("style") || rel.includes("css") ? walk(dirPath).filter((f) => CSS_EXTS.test(f)) : fs5.readdirSync(dirPath).filter((f) => CSS_EXTS.test(f)).map((f) => path5.join(dirPath, f));
+    for (const filePath of files) {
+      if (!assertSafeToRead(filePath)) continue;
+      const content = readFileSafe(filePath);
+      if (content) mergeColors(extractCssCustomProps(content));
+    }
+  }
+  for (const [name, hex] of allColors) {
+    const key = resolveThemeKey(name);
+    if (key && draft[key] === PLACEHOLDER) {
+      draft[key] = hex;
+    }
+  }
+  return draft;
+}
+function hasDetectedColors(draft) {
+  return Object.values(draft).some((v) => v !== PLACEHOLDER);
+}
+
+// src/bin/detectors/detectCredentials.ts
+var path6 = __toESM(require("path"), 1);
+var fs6 = __toESM(require("fs"), 1);
+var CREDENTIALS_BANNER = '// DEV/TEST/SEED ONLY \u2014 never production, never commit real passwords.\n// Extracted from .env.example and seeder files only.\n// Replace any "TODO: set from env \u2026" values with your actual dev/test credentials.';
+var SEEDER_PATH_PATTERNS = [
+  /[\\/]seeders?[\\/]/i,
+  /[\\/]seeds?[\\/]/i,
+  /prisma[\\/]seed\.[jt]s/i,
+  /db[\\/]seeds?[\\/]/i,
+  /[\\/]seed\.[jt]sx?$/i,
+  /devseed/i,
+  /seed\.(?:js|ts|mjs|cjs)$/i
+];
+function isSeederFile(filePath) {
+  const norm = filePath.replace(/\\/g, "/");
+  return SEEDER_PATH_PATTERNS.some((p) => p.test(norm));
+}
+function extractMatches(content) {
+  const out = [];
+  const lines = content.split("\n");
+  const FIELD_RE = /\b(email|login|username|password|phone|role)\s*[:=]\s*(?:["'`]([^"'`\r\n]+)["'`]|(process\.env\.(\w+)))/gi;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    let m;
+    FIELD_RE.lastIndex = 0;
+    while ((m = FIELD_RE.exec(line)) !== null) {
+      const type = m[1].toLowerCase();
+      let value;
+      if (m[3] !== void 0) {
+        value = `TODO: set from env ${m[4]} (use .env.example)`;
+      } else {
+        value = m[2].trim();
+        if (/^[<{]/.test(value) || /^(change[_-]?me|your[_-])/i.test(value)) continue;
+      }
+      out.push({ type, value, lineIdx: i, context: line });
+    }
+  }
+  return out;
+}
+var ROLE_HINTS = [
+  { role: "admin", patterns: [/admin/i, /superuser/i, /root/i, /operator/i] },
+  { role: "seller", patterns: [/seller/i, /vendor/i, /merchant/i, /store[_-]?owner/i] },
+  { role: "buyer", patterns: [/buyer/i, /customer/i, /client/i, /shopper/i] },
+  { role: "manager", patterns: [/manager/i, /supervisor/i] },
+  { role: "user", patterns: [/\buser\b/i, /\btest\b/i, /\bdemo\b/i] },
+  { role: "guest", patterns: [/guest/i, /anon/i, /public/i] }
+];
+function inferRole(context, login) {
+  const haystack = (context + " " + login).toLowerCase();
+  for (const { role, patterns } of ROLE_HINTS) {
+    if (patterns.some((p) => p.test(haystack))) return role;
+  }
+  return "user";
+}
+function groupMatches(matches) {
+  if (matches.length === 0) return [];
+  const clusters = [];
+  let current = [matches[0]];
+  for (let i = 1; i < matches.length; i++) {
+    const m = matches[i];
+    const prev = current[current.length - 1];
+    const isIdentifier = m.type === "email" || m.type === "login" || m.type === "username";
+    const clusterHasIdentifier = current.some(
+      (x) => x.type === "email" || x.type === "login" || x.type === "username"
+    );
+    if (m.lineIdx - prev.lineIdx > 20 || isIdentifier && clusterHasIdentifier) {
+      clusters.push(current);
+      current = [m];
+    } else {
+      current.push(m);
+    }
+  }
+  clusters.push(current);
+  const creds = [];
+  for (const cluster of clusters) {
+    const emailMatch = cluster.find((m) => m.type === "email");
+    const loginMatch = cluster.find((m) => m.type === "login" || m.type === "username");
+    const passMatch = cluster.find((m) => m.type === "password");
+    const roleMatch = cluster.find((m) => m.type === "role");
+    const login = (emailMatch ?? loginMatch)?.value;
+    const password = passMatch?.value;
+    if (!login && !password) continue;
+    const contextStr = cluster.map((m) => m.context).join(" ");
+    const role = roleMatch?.value ?? inferRole(contextStr, login ?? "");
+    creds.push({
+      role,
+      login: login ?? "TODO: set login",
+      password: password ?? "TODO: set password",
+      seeded: true
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return creds.filter((c) => {
+    const key = c.login + "|" + c.role;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+var SEEDER_SEARCH_DIRS = [
+  "seeders",
+  "seeds",
+  "prisma",
+  "db",
+  "database",
+  "src/database",
+  "src/db",
+  "scripts",
+  "src/scripts",
+  "src"
+];
+function detectCredentials(targetDir) {
+  const allMatches = [];
+  const envExample = path6.join(targetDir, ".env.example");
+  if (fs6.existsSync(envExample) && assertSafeToRead(envExample)) {
+    const content = readFileSafe(envExample);
+    if (content) allMatches.push(...extractMatches(content));
+  }
+  for (const rel of SEEDER_SEARCH_DIRS) {
+    const dirPath = path6.join(targetDir, rel);
+    if (!dirExists(dirPath)) continue;
+    const files = walk(dirPath).filter((f) => {
+      const ext = path6.extname(f);
+      return [".js", ".ts", ".mjs", ".cjs", ".json"].includes(ext) && isSeederFile(f) && assertSafeToRead(f);
+    });
+    for (const f of files) {
+      const content = readFileSafe(f);
+      if (content) allMatches.push(...extractMatches(content));
+    }
+  }
+  return groupMatches(allMatches);
+}
+
+// src/bin/generators/genConfig.ts
+function singleQuote(s) {
+  return `'${s.replace(/'/g, "\\'")}'`;
+}
+function serializeTheme(theme) {
+  const lines = [];
+  const keys = Object.keys(theme);
+  for (const key of keys) {
+    const val = theme[key];
+    const isPlaceholder = val === PLACEHOLDER;
+    if (isPlaceholder) {
+      lines.push(`    ${key}: ${singleQuote(val)}, // TODO: replace with your brand colour`);
+    } else {
+      lines.push(`    ${key}: ${singleQuote(val)},`);
+    }
+  }
+  return `  theme: {
+${lines.join("\n")}
+  }`;
+}
+function serializeCredentials(creds) {
+  if (creds.length === 0) {
+    return `  // ${CREDENTIALS_BANNER.replace(/\n/g, "\n  // ")}
+  credentials: [
+    // TODO: add dev/test credentials here (seeder/seed data)
+    // { role: 'buyer', login: 'buyer@test.com', password: 'test123', seeded: true },
+  ]`;
+  }
+  const banner = CREDENTIALS_BANNER.split("\n").map((l) => `  ${l}`).join("\n");
+  const rows = creds.map((c) => {
+    const lines = [
+      `    {`,
+      `      role:     ${singleQuote(c.role)},`,
+      `      login:    ${singleQuote(c.login)},`,
+      `      password: ${singleQuote(c.password)},`,
+      `      seeded:   true,`,
+      `    }`
+    ];
+    return lines.join("\n");
+  });
+  return `${banner}
+  credentials: [
+${rows.join(",\n")},
+  ]`;
+}
+function serializeStep(step) {
+  const what = `{ en: ${singleQuote(step.what.en)}, ar: ${singleQuote(step.what.ar)} }`;
+  return [
+    `        {`,
+    `          path: ${singleQuote(step.path)},`,
+    `          // TODO: grade \u2014 risk 'red' (money/auth/irreversible) | 'amber' (important) | 'green' (informational)`,
+    `          risk: 'green',`,
+    `          what: ${what},`,
+    `        }`
+  ].join("\n");
+}
+function serializeLane(lane) {
+  const role = `{ en: ${singleQuote(lane.role.en)}, ar: ${singleQuote(lane.role.ar)} }`;
+  const steps = lane.steps.map((s) => serializeStep(s)).join(",\n");
+  return [
+    `    {`,
+    `      id:    ${singleQuote(lane.id)},`,
+    `      color: ${singleQuote(lane.color ?? "#4f46e5")},`,
+    `      role:  ${role},`,
+    `      steps: [`,
+    steps,
+    `      ],`,
+    `    }`
+  ].join("\n");
+}
+function serializeJourney(journey) {
+  if (journey.length === 0) {
+    return `  journey: [
+    // TODO: add journey lanes here. See qa.preamble.md for guidance.
+    // { id: 'buyer', color: '#4f46e5', role: { en: 'Buyer', ar: '\u0645\u0634\u062A\u0631\u064A' }, steps: [...] },
+  ]`;
+  }
+  const lanes = journey.map((l) => serializeLane(l)).join(",\n");
+  return `  journey: [
+${lanes},
+  ]`;
+}
+function serializePreamble() {
+  return [
+    `  /**`,
+    `   * preamble \u2014 read by your AI coding agent (Claude Code, Cursor, Windsurf, etc.)`,
+    `   * when it processes a qa-notes-*.zip export. Fill every TODO field.`,
+    `   * Alternatively, fill qa.preamble.md and copy the values here.`,
+    `   */`,
+    `  preamble: {`,
+    `    projectName:       'TODO: Your Project Name',`,
+    `    oneLiner:          'TODO: one sentence describing what this project does',`,
+    `    stack:             'TODO: e.g. Next.js 14, React 18, Prisma, PostgreSQL, Tailwind',`,
+    `    runCommands:       'TODO: e.g. npm run dev   (starts on http://localhost:3000)',`,
+    `    conventions:       'TODO: coding conventions, naming patterns, file organisation',`,
+    `    invariants:        'TODO: things that must ALWAYS be true (e.g. prices \u2265 0, auth required for checkout)',`,
+    `    verifySteps:       'TODO: how to confirm a fix worked (e.g. reload + complete the flow)',`,
+    `    additionalContext: 'TODO: anything else the AI agent should know',`,
+    `  }`
+  ].join("\n");
+}
+function genConfigText(opts) {
+  const { namespace, isTypeScript, theme, journey, credentials, frameworkHints = [] } = opts;
+  const filename = isTypeScript ? "qa.config.ts" : "qa.config.js";
+  const hintsComment = frameworkHints.length > 0 ? ` *
+ * Auto-detected stack:
+${frameworkHints.map((h) => ` *   \u2022 ${h}`).join("\n")}` : "";
+  const typeImport = isTypeScript ? `import type { QaConfig } from 'qapture';
+
+` : `// @ts-check
+/** @type {import('qapture').QaConfig} */
+`;
+  const typeAnnotation = isTypeScript ? ": QaConfig" : "";
+  const exportStatement = `export default config;
+`;
+  const header = [
+    `/**`,
+    ` * qapture config \u2014 generated by \`qapture init\``,
+    ` *`,
+    ` * Fill every TODO field before mounting <Qapture config={config} />.`,
+    ` * Re-run \`qapture init --force\` only if you want to regenerate from scratch`,
+    ` * (your edits WILL be overwritten with --force).`,
+    ` *`,
+    ` * Schema reference: https://github.com/mohammed-farhood/qapture#qaconfig`,
+    hintsComment,
+    ` */`
+  ].filter((l) => l !== "").join("\n");
+  const themeBlock = serializeTheme(theme);
+  const credentialsBlock = serializeCredentials(credentials);
+  const journeyBlock = serializeJourney(journey);
+  const preambleBlock = serializePreamble();
+  const body = [
+    `const config${typeAnnotation} = {`,
+    `  namespace: ${singleQuote(namespace)},`,
+    ``,
+    themeBlock + ",",
+    ``,
+    `  brand: {`,
+    `    label: 'TODO: Your Project Name', // displayed in the QA panel header`,
+    `  },`,
+    ``,
+    `  loginField: {`,
+    `    en: 'TODO: e.g. Email or Username',`,
+    `    ar: 'TODO: e.g. \u0627\u0644\u0628\u0631\u064A\u062F \u0627\u0644\u0625\u0644\u0643\u062A\u0631\u0648\u0646\u064A',`,
+    `  },`,
+    ``,
+    credentialsBlock + ",",
+    ``,
+    journeyBlock + ",",
+    ``,
+    preambleBlock + ",",
+    `};`
+  ].join("\n");
+  const text = [header, "", typeImport + body, "", exportStatement].join("\n");
+  return { filename, text };
+}
+
+// src/bin/generators/genPreamble.ts
+function genPreambleText(opts = {}) {
+  const { projectName, frameworkHints = [] } = opts;
+  const detectedName = projectName ? `_${projectName}_` : "_TODO: Your Project Name_";
+  const stackHint = frameworkHints.length > 0 ? frameworkHints.join(", ") : "TODO: e.g. Next.js 14, React 18, Prisma, PostgreSQL, Tailwind CSS";
+  return `# Qapture \u2014 Project Preamble
+
+> **What is this file?**
+> Fill in the sections below so your AI coding agent (Claude Code, Cursor,
+> Windsurf, etc.) understands the project before it acts on a \`qa-notes-*.zip\`
+> export. When you're happy with the content, copy the values into the \`preamble\`
+> block of \`qa.config.ts\`.
+>
+> You can fill this manually OR paste it into your terminal agent and ask it to
+> auto-populate from the codebase.
+
+---
+
+## Project
+
+**Name:** ${detectedName}
+
+**One-liner:**
+TODO: one sentence \u2014 what does this project do for the user?
+
+**Stack:**
+${stackHint}
+
+---
+
+## Run Commands
+
+<!-- How to start the dev server, seed the database, run tests, etc. -->
+
+\`\`\`bash
+# TODO: fill in your start command(s)
+# e.g.:
+#   npm run dev          # starts on http://localhost:3000
+#   npm run db:seed      # seed dev database
+#   npm run test         # run unit/integration tests
+\`\`\`
+
+---
+
+## Conventions
+
+<!-- Coding conventions, naming patterns, file organisation rules. -->
+<!-- Example: "All server actions live in src/actions/*.ts" -->
+
+TODO: describe your codebase conventions, naming patterns, and any structural
+rules the AI should respect when making changes (e.g. "always use Zod for
+input validation", "mutations go through tRPC", "never import from ../db directly").
+
+---
+
+## Invariants
+
+<!-- Things that MUST always be true \u2014 the AI must never violate these. -->
+<!-- Example: "Cart total is always \u2265 0" or "Checkout requires authentication" -->
+
+TODO: list your key business invariants, one per line:
+- TODO: invariant 1
+- TODO: invariant 2
+- TODO: ...
+
+---
+
+## Verify Steps
+
+<!-- How to confirm a fix worked \u2014 the AI follows these steps after making a change. -->
+
+TODO: describe your verification workflow, e.g.:
+1. Run \`npm run dev\`
+2. Log in as the relevant role (see credentials in \`qa.config.ts\`)
+3. Navigate to the affected page
+4. Reproduce the original issue to confirm it's fixed
+5. Check no regressions on adjacent paths
+
+---
+
+## Additional Context
+
+<!-- Anything else the AI agent should know: third-party integrations, known
+     quirks, pending migrations, feature flags, etc. -->
+
+TODO: add any extra context here.
+
+---
+
+_Generated by \`qapture init\`. See https://github.com/mohammed-farhood/qapture for docs._
+`;
+}
+
+// src/bin/init.ts
+var REPO_URL = "https://github.com/mohammed-farhood/qapture";
+var PKG_VERSION = (() => {
+  try {
+    const candidates = [
+      path7.join(__dirname, "..", "..", "package.json"),
+      path7.join(__dirname, "..", "package.json"),
+      path7.join(__dirname, "package.json")
+    ];
+    for (const p of candidates) {
+      if (fs7.existsSync(p)) {
+        const pkg = JSON.parse(fs7.readFileSync(p, "utf8"));
+        if (pkg.version) return pkg.version;
+      }
+    }
+  } catch {
+  }
+  return "0.x";
+})();
+function readTargetPkg(targetDir) {
+  try {
+    const raw = fs7.readFileSync(path7.join(targetDir, "package.json"), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function hasFile(targetDir, ...names) {
+  return names.some((n) => fs7.existsSync(path7.join(targetDir, n)));
+}
+function detectFrameworkHints(targetDir, pkg) {
+  const hints = [];
+  const deps = {
+    ...pkg["dependencies"] ?? {},
+    ...pkg["devDependencies"] ?? {}
+  };
+  const hasDep = (name) => name in deps;
+  if (hasDep("next")) hints.push("Next.js");
+  if (hasDep("nuxt")) hints.push("Nuxt");
+  if (hasDep("astro")) hints.push("Astro");
+  if (hasDep("vite") && !hasDep("next")) hints.push("Vite");
+  if (hasDep("remix")) hints.push("Remix");
+  if (hasDep("gatsby")) hints.push("Gatsby");
+  if (hasDep("svelte")) hints.push("Svelte");
+  if (hasDep("react")) hints.push("React");
+  if (hasDep("vue")) hints.push("Vue");
+  if (hasDep("tailwindcss")) hints.push("Tailwind CSS");
+  if (hasDep("styled-components")) hints.push("styled-components");
+  if (hasDep("@prisma/client") || hasDep("prisma")) hints.push("Prisma");
+  if (hasDep("drizzle-orm")) hints.push("Drizzle ORM");
+  if (hasDep("mongoose")) hints.push("MongoDB/Mongoose");
+  if (hasDep("typeorm")) hints.push("TypeORM");
+  if (hasDep("next-auth") || hasDep("@auth/core")) hints.push("NextAuth");
+  if (hasDep("lucia")) hints.push("Lucia");
+  if (hasDep("clerk")) hints.push("Clerk");
+  if (hasFile(targetDir, "tsconfig.json")) hints.push("TypeScript");
+  return hints;
+}
+function printUsage() {
+  process2.stdout.write(
+    `
+qapture CLI v${PKG_VERSION}
+
+Usage:
+  qapture init [target-dir] [--force]   Scaffold config + artifacts into target-dir
+  qapture version                        Print version
+
+Options:
+  --force  Overwrite qa.config.* and qa.preamble.md if they already exist
+           (SKILL.md is always refreshed regardless of --force)
+
+Docs: ${REPO_URL}
+
+`
+  );
+}
+function printVersion() {
+  process2.stdout.write(`qapture ${PKG_VERSION}
+`);
+}
+var DIVIDER = "\u2500".repeat(60);
+function printSummary(targetDir, configFile, results, routeCount, credCount, colorsDetected) {
+  const icon = (r) => r === "skipped" ? "  (skip)" : "  \u2713";
+  const configLabel = configFile;
+  const preambleLabel = "qa.preamble.md";
+  const skillLabel = ".claude/skills/qapture/SKILL.md";
+  const agentsLabel = "AGENTS.md";
+  const configNote = results.config === "skipped" ? " (already exists \u2014 use --force to overwrite)" : " (review & fill TODOs)";
+  const preambleNote = results.preamble === "skipped" ? " (already exists \u2014 use --force to overwrite)" : " (fill project context)";
+  const agentsNote = results.agents === "created" ? " (created)" : results.agents === "replaced" ? " (section updated)" : " (section appended)";
+  process2.stdout.write(
+    `
+${DIVIDER}
+  qapture init \u2014 done!
+${DIVIDER}
+
+  Files:
+${icon(results.config)}  ${configLabel}${configNote}
+${icon(results.preamble)}  ${preambleLabel}${preambleNote}
+  \u2713  ${skillLabel} (always refreshed)
+  \u2713  ${agentsLabel}${agentsNote}
+
+  Detected:
+    \u2022 Routes/steps : ${routeCount > 0 ? routeCount : "none (fallback placeholder added)"}
+    \u2022 Brand colours: ${colorsDetected ? "partial palette detected" : "none (all #REPLACE_ME)"}
+    \u2022 Credentials  : ${credCount > 0 ? credCount + " row(s) from .env.example/seeders" : "none (add manually)"}
+
+${DIVIDER}
+  Mount the widget near your app root:
+${DIVIDER}
+
+    import { Qapture } from 'qapture';
+    import config from './${configFile.replace(/\.[jt]s$/, "")}';
+
+    // Render once near your app root:
+    <Qapture config={config} />
+
+${DIVIDER}
+  Next steps:
+${DIVIDER}
+
+    1. Fill in ${preambleLabel} with your project context
+       (or ask your terminal agent to auto-populate it from the codebase)
+    2. Sync the preamble into the preamble block of ${configLabel}
+    3. Grade JOURNEY risk levels \u2014 change  risk: 'green'  to:
+         'red'   \u2192 money / auth / irreversible flows
+         'amber' \u2192 important but recoverable flows
+         'green' \u2192 informational / display only  (current default)
+    4. Fill remaining TODO: fields in ${configLabel}
+    5. Run your app and open Qapture (shortcut: Shift+Alt+Q)
+
+${DIVIDER}
+  IDE advisory:
+${DIVIDER}
+
+    Cursor   \u2192 copy the qapture block from AGENTS.md
+               into  .cursor/rules/qapture.md
+
+    Windsurf \u2192 append the qapture block from AGENTS.md
+               to    .windsurf/rules.md
+
+  Docs: ${REPO_URL}
+${DIVIDER}
+
+`
+  );
+}
+function main(argv2) {
+  const args = parseArgs(argv2);
+  if (args.command === "version") {
+    printVersion();
+    process2.exit(0);
+  }
+  if (args.command === "help") {
+    printUsage();
+    process2.exit(0);
+  }
+  const targetDir = path7.resolve(args.dir);
+  const { force } = args;
+  if (!fs7.existsSync(targetDir)) {
+    process2.stderr.write(`
+Error: target directory does not exist: ${targetDir}
+
+`);
+    process2.exit(1);
+  }
+  if (!fs7.statSync(targetDir).isDirectory()) {
+    process2.stderr.write(`
+Error: ${targetDir} is not a directory
+
+`);
+    process2.exit(1);
+  }
+  process2.stdout.write(`
+qapture init \u2014 scanning ${targetDir} ...
+`);
+  const pkg = readTargetPkg(targetDir);
+  const frameworkHints = detectFrameworkHints(targetDir, pkg);
+  const isTypeScript = hasFile(targetDir, "tsconfig.json");
+  process2.stdout.write(`  Detecting routes ...
+`);
+  const journey = detectRoutes(targetDir);
+  const routeCount = journey.reduce((n, lane) => n + lane.steps.length, 0);
+  process2.stdout.write(`  Detecting theme ...
+`);
+  const theme = detectTheme(targetDir);
+  const colorsDetected = hasDetectedColors(theme);
+  process2.stdout.write(`  Detecting credentials (safe sources only) ...
+`);
+  const credentials = detectCredentials(targetDir);
+  const namespace = typeof pkg["name"] === "string" && pkg["name"].trim() ? pkg["name"].trim().replace(/^@[^/]+\//, "") : "qapture";
+  const projectName = typeof pkg["name"] === "string" && pkg["name"].trim() ? pkg["name"].trim() : void 0;
+  process2.stdout.write(`  Generating files ...
+`);
+  const { filename: configFilename, text: configText } = genConfigText({
+    namespace,
+    isTypeScript,
+    theme,
+    journey,
+    credentials,
+    frameworkHints
+  });
+  const preambleText = genPreambleText({ projectName, frameworkHints });
+  const configPath = path7.join(targetDir, configFilename);
+  const preamblePath = path7.join(targetDir, "qa.preamble.md");
+  const skillPath = path7.join(targetDir, ".claude", "skills", "qapture", "SKILL.md");
+  const agentsMdPath = path7.join(targetDir, "AGENTS.md");
+  const configResult = writeIfAbsent(configPath, configText, force);
+  const preambleResult = writeIfAbsent(preamblePath, preambleText, force);
+  writeAlways(skillPath, SKILL_default);
+  const skillResult = "written";
+  const agentsResult = mergeAgentsMd(agentsMdPath, AGENTS_SECTION_default);
+  printSummary(
+    targetDir,
+    configFilename,
+    { config: configResult, preamble: preambleResult, skill: skillResult, agents: agentsResult },
+    routeCount,
+    credentials.length,
+    colorsDetected
+  );
+}
+main(process2.argv.slice(2));