qatools-cli 1.0.0 → 1.1.0

package/qatools.js

@@ -38,10 +38,38 @@ async function authenticate(options) {
   const email = options.email || creds?.email;
   const password = options.password || creds?.password;
   const refreshToken = creds?.refreshToken;
+  const apiKey = process.env.QATOOLS_API_KEY || creds?.apiKey;
+
+  if (apiKey) {
+    try {
+      const authRes = await fetch("https://us-central1-qatools-app.cloudfunctions.net/authenticateWithApiKey", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ data: { apiKey } }),
+      });
+      const authData = await authRes.json();
+      if (authData.result?.customToken) {
+        await signInWithCustomToken(auth, authData.result.customToken);
+        // Set projectId from API key response if not already configured
+        if (authData.result.projectId && (!creds?.projectId || process.env.QATOOLS_API_KEY)) {
+          const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
+          const existing = creds || {};
+          existing.projectId = authData.result.projectId;
+          existing.projectName = authData.result.projectName;
+          existing.apiKey = apiKey;
+          fs.writeFileSync(configPath, JSON.stringify(existing, null, 2));
+        }
+        return;
+      }
+      throw new Error("API key authentication failed");
+    } catch (e) {
+      console.error("API key auth failed:", e.message);
+      process.exit(1);
+    }
+  }
 
   if (refreshToken) {
     try {
-      // Exchange refresh token for a new ID token, then sign in
+      // Exchange refresh token for a new ID token
       const res = await fetch(`https://securetoken.googleapis.com/v1/token?key=${firebaseConfig.apiKey}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
@@ -49,8 +77,10 @@ async function authenticate(options) {
       });
       const data = await res.json();
       if (!data.id_token) throw new Error("Refresh failed");
-      // Use the auth emulator approach: sign in with custom token from server
-      // Actually we need to use signInWithCustomToken, so mint one
+
+      // Sign in with the ID token via signInWithCredential
+      const { GoogleAuthProvider, signInWithCredential } = require('firebase/auth');
+      // First try: sign in directly by minting custom token via REST with proper callable format
       const mintRes = await fetch(`https://us-central1-qatools-app.cloudfunctions.net/mintCliToken`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${data.id_token}` },
@@ -61,9 +91,23 @@ async function authenticate(options) {
         await signInWithCustomToken(auth, mintData.result.customToken);
         return;
       }
-      throw new Error("Mint failed");
+
+      // Fallback: use the ID token to sign in via custom token REST API
+      const signInRes = await fetch(`https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${firebaseConfig.apiKey}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: data.id_token, returnSecureToken: true }),
+      });
+      const signInData = await signInRes.json();
+      if (signInData.error) throw new Error(signInData.error.message);
+
+      // Use the refresh token from sign-in to authenticate Firebase SDK
+      await signInWithCustomToken(auth, data.id_token).catch(() => {});
+
+      // If all else fails, try email sign in if available
+      throw new Error("Could not authenticate with refresh token");
     } catch (e) {
-      console.error("Google token refresh failed:", e.message, "\nRun 'qatools login --google' again.");
+      console.error("Token refresh failed:", e.message, "\nRun 'qatools login --google' to re-authenticate.");
       process.exit(1);
     }
   }
@@ -200,15 +244,62 @@ program
     process.exit(0);
   });
 
+program
+  .command("projects")
+  .description("List all your projects")
+  .action(async (options) => {
+    await authenticate(options);
+    const listProjects = httpsCallable(functions, "listProjects");
+    try {
+      const result = await listProjects({});
+      const projects = result.data.projects;
+      console.log(`\n${projects.length} project(s):\n`);
+      projects.forEach((p, i) => {
+        console.log(`  ${i + 1}. ${p.name} ${p.claudeEnabled ? '🤖' : ''} (${p.id})`);
+      });
+    } catch (e) {
+      console.error("Failed:", e.message);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("project-update")
+  .description("Update project name or description")
+  .option("--name <name>", "New project name")
+  .option("--description <desc>", "New project description")
+  .option("-i, --id <projectId>", "Project ID (defaults to configured project)")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.id || creds?.projectId;
+    if (!projectId) { console.error("No project. Run: qatools setup"); process.exit(1); }
+    if (!options.name && !options.description) { console.error("Specify --name and/or --description"); process.exit(1); }
+    const updateProject = httpsCallable(functions, "updateProjectFields");
+    try {
+      const updates = {};
+      if (options.name) updates.name = options.name;
+      if (options.description) updates.description = options.description;
+      await updateProject({ projectId, updates });
+      console.log(`Project updated.`);
+      if (options.name) console.log(`  Name: ${options.name}`);
+      if (options.description) console.log(`  Description: ${options.description}`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+    }
+    process.exit(0);
+  });
+
 program
   .command("pending")
   .description("List test sessions awaiting Claude analysis")
+  .option("--project <id>", "Target project ID (overrides default; omit both to scan all your projects)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    const projectId = creds?.projectId;
+    const projectId = options.project || creds?.projectId;
 
     const pendingSessions = httpsCallable(functions, "pendingSessions");
     try {
@@ -237,8 +328,9 @@ program
 program
   .command("backlog")
   .description("List backlog items for configured project")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("--sprint <id>", "Filter by sprint ID")
-  .option("--status <statuses>", "Filter by status (comma-separated: new,in_progress,on_hold)")
+  .option("--status <statuses>", "Filter by status (comma-separated: open,in_progress,resolved,rejected)")
   .option("--assigned <email>", "Filter by assignee")
   .option("-o, --output <path>", "Output file (default: stdout)")
   .option("-e, --email <email>", "Login email")
@@ -246,11 +338,12 @@ program
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const listBacklog = httpsCallable(functions, "listBacklog");
     try {
-      const filters = { projectId: creds.projectId };
+      const filters = { projectId };
       if (options.sprint) filters.sprintId = options.sprint;
       if (options.status) filters.status = options.status.split(",");
       if (options.assigned) filters.assignedTo = options.assigned;
@@ -274,17 +367,19 @@ program
   .command("sprint-items")
   .description("List all items in a sprint")
   .requiredOption("--sprint <id>", "Sprint ID")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("-o, --output <path>", "Output file")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const getSprintItems = httpsCallable(functions, "getSprintItems");
     try {
-      const result = await getSprintItems({ projectId: creds.projectId, sprintId: options.sprint });
+      const result = await getSprintItems({ projectId, sprintId: options.sprint });
       const data = result.data;
       if (options.output) {
         fs.writeFileSync(path.resolve(options.output), JSON.stringify(data, null, 2));
@@ -302,16 +397,18 @@ program
 program
   .command("sprints")
   .description("List sprints for configured project")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const listSprints = httpsCallable(functions, "listSprints");
     try {
-      const result = await listSprints({ projectId: creds.projectId });
+      const result = await listSprints({ projectId });
       for (const s of result.data.sprints) {
         console.log(`  ${s.id}  ${s.name}  [${s.status}]  Release: ${s.releaseDate || "N/A"}`);
       }
@@ -326,11 +423,13 @@ program
   .command("backlog-create")
   .description("Create a new backlog item")
   .requiredOption("-d, --description <text>", "Description")
-  .option("-t, --type <type>", "Type: bug, task, improvement, feature, epic, story", "task")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-t, --type <type>", "Type: bug, improvement, requirement_gap, technical_defect", "bug")
   .option("--priority <n>", "Priority: 1 (high), 2 (medium), 3 (low)", "2")
   .option("--assigned <email>", "Assign to")
+  .option("--developer <email>", "Developer (responsible)")
   .option("--sprint <id>", "Sprint ID")
-  .option("--parent <label>", "Parent item label (e.g. STORY-5)")
+  .option("--parent <label>", "Parent item label (e.g. BUG-5)")
   .option("--requirement-key <key>", "Requirement key (e.g. auth.login)")
   .option("--tags <tags>", "Tags (comma-separated)")
   .option("-e, --email <email>", "Login email")
@@ -338,22 +437,25 @@ program
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const createItem = httpsCallable(functions, "createBacklogItem");
     try {
       const result = await createItem({
-        projectId: creds.projectId,
+        projectId,
         type: options.type,
         description: options.description,
         priority: parseInt(options.priority, 10),
         assignedTo: options.assigned || "",
+        developer: options.developer || "",
         sprintId: options.sprint || "",
         parentId: options.parent || "",
         requirementKey: options.requirementKey || "",
-        tags: options.tags ? options.tags.split(",").map(t => t.trim()) : [],
+        tags: options.tags ? options.tags.split(",").map(t => t.trim().toLowerCase()) : [],
       });
       console.log(`Created: ${result.data.type.toUpperCase()}-${result.data.bugNumber} (${result.data.id})`);
+      if (options.tags) console.log(`  Tags: ${options.tags}`);
     } catch (e) {
       console.error("Failed:", e.message);
       process.exit(1);
@@ -364,17 +466,19 @@ program
 program
   .command("templates")
   .description("List templates and their review status")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("--status <status>", "Filter: draft, pending_review, approved, rejected")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const listTemplates = httpsCallable(functions, "listTemplates");
     try {
-      const result = await listTemplates({ projectId: creds.projectId, status: options.status || null });
+      const result = await listTemplates({ projectId, status: options.status || null });
       const templates = result.data.templates;
       if (templates.length === 0) {
         console.log("No templates found.");
@@ -392,19 +496,112 @@ program
     process.exit(0);
   });
 
+program
+  .command("requirements")
+  .description("List requirements with rich filters. Superseded reqs are hidden by default.")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("--status <statuses>", "Filter by status (comma-separated): draft,approved,rejected,implemented,tested,superseded")
+  .option("--epic <key>", "Only reqs linked to this epic")
+  .option("--no-epic", "Only reqs WITHOUT an epic")
+  .option("--type <type>", "Filter by type: functional, non-functional")
+  .option("--with-coverage", "Only reqs that have at least one test case in any template")
+  .option("--without-coverage", "Only reqs with NO test coverage")
+  .option("--include-superseded", "Include superseded reqs (hidden by default)")
+  .option("--json", "Output as JSON to stdout (machine-readable)")
+  .option("-o, --output <file>", "Write JSON output to file")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    const listReqs = httpsCallable(functions, "listRequirements");
+    try {
+      // Server-side status filter only works for a single status; do all filtering client-side for consistency
+      const result = await listReqs({ projectId, status: null });
+      let reqs = result.data.requirements;
+
+      // Default: hide superseded
+      if (!options.includeSuperseded) reqs = reqs.filter(r => r.status !== "superseded");
+
+      // Status (comma-separated)
+      if (options.status) {
+        const statuses = new Set(options.status.split(",").map(s => s.trim()));
+        reqs = reqs.filter(r => statuses.has(r.status));
+      }
+
+      // Epic
+      if (options.epic) reqs = reqs.filter(r => r.epicKey === options.epic);
+      // commander turns --no-epic into options.epic === false
+      if (options.epic === false) reqs = reqs.filter(r => !r.epicKey);
+
+      // Type
+      if (options.type) reqs = reqs.filter(r => r.type === options.type);
+
+      // Coverage filters require loading templates
+      if (options.withCoverage || options.withoutCoverage) {
+        const listTemplates = httpsCallable(functions, "listTemplates");
+        const tplResult = await listTemplates({ projectId, status: null });
+        // listTemplates returns summary only — we need full templates for test cases
+        // Use the full templates list via a different path: load each template (or rely on coverage server-side later)
+        // For now: scan template summaries for requirementKey if present, otherwise we have to fall back
+        const covered = new Set();
+        for (const t of (tplResult.data.templates || [])) {
+          // Some template responses include sections, others only summaries
+          for (const sec of (t.sections || [])) {
+            for (const test of (sec.tests || [])) {
+              if (test.requirementKey) covered.add(test.requirementKey);
+            }
+          }
+        }
+        if (options.withCoverage) reqs = reqs.filter(r => covered.has(r.key));
+        if (options.withoutCoverage) reqs = reqs.filter(r => !covered.has(r.key));
+        if (covered.size === 0 && (options.withCoverage || options.withoutCoverage)) {
+          console.error("Note: listTemplates returned no test-case data. Coverage filter may be unreliable. Use the web app for accurate coverage.");
+        }
+      }
+
+      // Output
+      if (options.json) {
+        console.log(JSON.stringify(reqs, null, 2));
+        process.exit(0);
+      }
+      if (options.output) {
+        fs.writeFileSync(options.output, JSON.stringify(reqs, null, 2));
+        console.log(`Written ${reqs.length} requirements to ${options.output}`);
+      } else {
+        console.log(`\n${reqs.length} requirement${reqs.length !== 1 ? 's' : ''}:\n`);
+        for (const r of reqs) {
+          const badge = r.status === "rejected" ? "❌" : r.status === "approved" ? "✅" : r.status === "tested" ? "🟢" : r.status === "implemented" ? "🟡" : r.status === "superseded" ? "🗑" : "📝";
+          const epic = r.epicKey ? ` epic:${r.epicKey}` : ' (no epic)';
+          console.log(`  ${badge} [${r.key}]${epic} ${r.title} (${r.status})`);
+          if (r.reviewComment) console.log(`     💬 ${r.reviewComment}`);
+        }
+      }
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
 program
   .command("requirement-keys")
   .description("List all requirement keys in the project (from backlog + templates)")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const listKeys = httpsCallable(functions, "listRequirementKeys");
     try {
-      const result = await listKeys({ projectId: creds.projectId });
+      const result = await listKeys({ projectId });
       const keys = result.data.keys;
       if (keys.length === 0) {
         console.log("No requirement keys found.");
@@ -425,16 +622,372 @@ program
     process.exit(0);
   });
 
+program
+  .command("requirement-create")
+  .description("Upload requirements from JSON file. Each req may include a 'status' field (draft/approved/rejected/implemented/tested); defaults to draft.")
+  .requiredOption("-f, --file <path>", "Path to requirements JSON file")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("--force", "Skip semantic similarity check (allow create even if similar key/title exists)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    const fs = require("fs");
+    const data = JSON.parse(fs.readFileSync(options.file, "utf8"));
+    const requirements = Array.isArray(data) ? data : (data.requirements || [data]);
+
+    const createReq = httpsCallable(functions, "createRequirement");
+    let created = 0, skipped = 0, similar = 0;
+    const similarReports = [];
+    for (const req of requirements) {
+      try {
+        const payload = { projectId, ...req };
+        if (options.force) payload.force = true;
+        const result = await createReq(payload);
+        if (result.data.error === "duplicate") {
+          skipped++;
+          process.stdout.write(`\r  Created ${created}, skipped ${skipped} (dup), similar ${similar} / ${requirements.length}`);
+        } else if (result.data.error === "similar_exists") {
+          similar++;
+          similarReports.push({ attempted: req, matches: result.data.matches });
+          process.stdout.write(`\r  Created ${created}, skipped ${skipped} (dup), similar ${similar} / ${requirements.length}`);
+        } else {
+          created++;
+          process.stdout.write(`\r  Created ${created}, skipped ${skipped} (dup), similar ${similar} / ${requirements.length}`);
+        }
+      } catch (e) {
+        console.error(`\nFailed to create ${req.key}: ${e.message}`);
+      }
+    }
+    console.log(`\n\nDone. ${created} created, ${skipped} skipped (exact dup), ${similar} blocked (semantically similar).`);
+    if (similar > 0) {
+      console.log(`\nSimilar matches found — review before deciding:\n`);
+      for (const rep of similarReports) {
+        console.log(`  Attempted: [${rep.attempted.key}] ${rep.attempted.title}`);
+        for (const m of rep.matches) {
+          console.log(`    ↳ similar (${m.matchedOn}): [${m.key}] ${m.title} (${m.status}, id=${m.id})`);
+        }
+      }
+      console.log(`\nResolve by either:\n  - editing your input to align with the existing key/title\n  - re-running with --force if you really mean a separate requirement`);
+      process.exit(2);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("sync")
+  .description("Sync App Context from qa-tools into a CLAUDE.md block")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-o, --output <path>", "Path to file to update (auto: .claude/CLAUDE.md if it exists, else CLAUDE.md)")
+  .option("--check", "Exit 1 if file is out of sync (does not modify)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    // Default output: prefer .claude/CLAUDE.md if it exists, else CLAUDE.md in cwd
+    if (!options.output) {
+      options.output = fs.existsSync(".claude/CLAUDE.md") ? ".claude/CLAUDE.md" : "CLAUDE.md";
+    }
+
+    const getCtx = httpsCallable(functions, "getAppContext");
+    let ctx;
+    try {
+      const result = await getCtx({ projectId });
+      ctx = result.data.appContext;
+    } catch (e) {
+      console.error("Failed to fetch App Context:", e.message);
+      process.exit(1);
+    }
+    if (!ctx) {
+      console.error(`No App Context defined for project ${projectId}.`);
+      process.exit(1);
+    }
+
+    const md = renderAppContextMarkdown(ctx, projectId);
+    const beginMarker = "<!-- BEGIN qatools-context (auto-synced from qa-tools, do not edit by hand) -->";
+    const endMarker = "<!-- END qatools-context -->";
+    const block = `${beginMarker}\n${md}\n${endMarker}`;
+
+    const filePath = path.resolve(options.output);
+    let existing = "";
+    if (fs.existsSync(filePath)) existing = fs.readFileSync(filePath, "utf8");
+
+    let updated;
+    const beginIdx = existing.indexOf(beginMarker);
+    const endIdx = existing.indexOf(endMarker);
+    if (beginIdx >= 0 && endIdx > beginIdx) {
+      updated = existing.slice(0, beginIdx) + block + existing.slice(endIdx + endMarker.length);
+    } else {
+      const sep = existing && !existing.endsWith("\n") ? "\n\n" : (existing ? "\n" : "");
+      updated = existing + sep + block + "\n";
+    }
+
+    if (options.check) {
+      if (existing === updated) {
+        console.log(`✓ ${options.output} is in sync with project ${projectId}`);
+        process.exit(0);
+      } else {
+        console.error(`✗ ${options.output} is out of sync with project ${projectId}. Run: qatools sync`);
+        process.exit(1);
+      }
+    }
+
+    if (existing === updated) {
+      console.log(`✓ ${options.output} already in sync (no changes)`);
+    } else {
+      fs.writeFileSync(filePath, updated);
+      console.log(`✓ ${options.output} updated from project ${projectId} (${ctx.name})`);
+    }
+    process.exit(0);
+  });
+
+function renderAppContextMarkdown(ctx, projectId) {
+  const lines = [];
+  const ts = new Date().toISOString();
+  lines.push(`<!-- Last synced: ${ts} from project ${projectId} -->`);
+  lines.push("");
+  lines.push(`## ${ctx.name || "Project Context"}`);
+  lines.push("");
+  if (ctx.purpose) { lines.push("### Purpose"); lines.push(ctx.purpose); lines.push(""); }
+  if (ctx.domainObjects?.length) {
+    lines.push("### Domain Objects");
+    lines.push(ctx.domainObjects.map(o => `- ${o}`).join("\n"));
+    lines.push("");
+  }
+  if (ctx.actors?.length) {
+    lines.push("### Actors");
+    lines.push(ctx.actors.map(a => `- ${a}`).join("\n"));
+    lines.push("");
+  }
+  if (ctx.stack?.length) {
+    lines.push("### Tech Stack");
+    for (const s of ctx.stack) {
+      const v = s.version ? ` ${s.version}` : "";
+      const n = s.notes ? ` — ${s.notes}` : "";
+      lines.push(`- **${s.layer}**: ${s.technology}${v}${n}`);
+    }
+    lines.push("");
+  }
+  if (ctx.architecture) { lines.push("### Architecture"); lines.push(ctx.architecture); lines.push(""); }
+  if (ctx.security?.length) {
+    lines.push("### Security");
+    lines.push(ctx.security.map(s => `- ${s}`).join("\n"));
+    lines.push("");
+  }
+  if (ctx.aiRules?.length) {
+    lines.push("### AI Rules");
+    ctx.aiRules.forEach((r, i) => lines.push(`${i + 1}. ${r}`));
+    lines.push("");
+  }
+  if (ctx.constraints?.length) {
+    lines.push("### Constraints");
+    lines.push(ctx.constraints.map(c => `- ${c}`).join("\n"));
+    lines.push("");
+  }
+  if (ctx.conventions?.length) {
+    lines.push("### Conventions");
+    for (const c of ctx.conventions) lines.push(`- **${c.area}**: ${c.rule}`);
+    lines.push("");
+  }
+  if (ctx.environments?.length) {
+    lines.push("### Environments");
+    for (const e of ctx.environments) {
+      const url = e.url ? ` — ${e.url}` : "";
+      const notes = e.notes ? ` (${e.notes})` : "";
+      lines.push(`- **${e.name}**${url}${notes}`);
+    }
+    lines.push("");
+  }
+  if (ctx.integrations?.length) {
+    lines.push("### Integrations");
+    for (const i of ctx.integrations) {
+      const purpose = i.purpose ? ` — ${i.purpose}` : "";
+      lines.push(`- **${i.name}**${purpose}`);
+    }
+    lines.push("");
+  }
+  if (ctx.sections?.length) {
+    for (const s of ctx.sections) {
+      lines.push(`### ${s.title}`);
+      // defensive: escape end-comment markers only in user content so it can't break our END marker
+      lines.push((s.content || "").replace(/-->/g, "--\\>"));
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
+program
+  .command("next")
+  .description("Show what Claude should work on next in this project")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("--json", "Output raw JSON instead of formatted text")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const getAgenda = httpsCallable(functions, "getProjectAgenda");
+    let result;
+    try {
+      result = await getAgenda({ projectId });
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    const data = result.data;
+    if (options.json) {
+      console.log(JSON.stringify(data, null, 2));
+      process.exit(0);
+    }
+    // Formatted output
+    console.log(`\n  ${data.projectName} (${data.projectId})`);
+    if (data.activeSprint) console.log(`  Active sprint: ${data.activeSprint.name}`);
+    console.log("");
+
+    const sections = [];
+    if (data.agenda.pendingSessions.length) {
+      const items = data.agenda.pendingSessions.map(s => `  • "${s.templateName}" (sess: ${s.id})`);
+      sections.push({
+        icon: "🔴",
+        title: `URGENT — ${data.agenda.pendingSessions.length} session${data.agenda.pendingSessions.length > 1 ? 's' : ''} waiting for analysis`,
+        items,
+        next: `qatools read-session <id>  →  qatools upload-analysis <file>`,
+      });
+    }
+    if (data.agenda.approvedNoCoverage.length) {
+      const items = data.agenda.approvedNoCoverage.slice(0, 10).map(r => `  • [${r.key}] ${r.title}`);
+      if (data.agenda.approvedNoCoverage.length > 10) items.push(`  • ... and ${data.agenda.approvedNoCoverage.length - 10} more`);
+      sections.push({
+        icon: "🟡",
+        title: `${data.agenda.approvedNoCoverage.length} approved requirement${data.agenda.approvedNoCoverage.length > 1 ? 's' : ''} without test coverage`,
+        items,
+        next: `write a template covering these  →  qatools template-upload <file>`,
+      });
+    }
+    if (data.agenda.continuousUnverified.length) {
+      const items = data.agenda.continuousUnverified.map(r => `  • [${r.key}] ${r.title}`);
+      sections.push({
+        icon: "🟢",
+        title: `${data.agenda.continuousUnverified.length} continuous compliance req${data.agenda.continuousUnverified.length > 1 ? 's' : ''} need verification for "${data.agenda.continuousUnverified[0].sprintName}"`,
+        items,
+        next: `verify each against this sprint's diff and record result via UI Sprintar tab`,
+      });
+    }
+    if (data.agenda.sprintReqsNotTested.length) {
+      const items = data.agenda.sprintReqsNotTested.slice(0, 10).map(r => `  • [${r.key}] ${r.title} (${r.status})`);
+      if (data.agenda.sprintReqsNotTested.length > 10) items.push(`  • ... and ${data.agenda.sprintReqsNotTested.length - 10} more`);
+      sections.push({
+        icon: "🟢",
+        title: `${data.agenda.sprintReqsNotTested.length} requirement${data.agenda.sprintReqsNotTested.length > 1 ? 's' : ''} in active sprint not yet tested`,
+        items,
+        next: `implement, test, then  qatools requirement-update -i <id> --status tested`,
+      });
+    }
+    if (data.agenda.draftReqs.length) {
+      const items = data.agenda.draftReqs.slice(0, 10).map(r => `  • [${r.key}] ${r.title}${r.hasAC ? '' : '  (no AC)'}`);
+      if (data.agenda.draftReqs.length > 10) items.push(`  • ... and ${data.agenda.draftReqs.length - 10} more`);
+      sections.push({
+        icon: "⚪",
+        title: `${data.agenda.draftReqs.length} draft requirement${data.agenda.draftReqs.length > 1 ? 's' : ''} need acceptance criteria / approval`,
+        items,
+        next: `qatools requirement-update -i <id> --status approved  (or refine AC first)`,
+      });
+    }
+
+    if (sections.length === 0) {
+      console.log("  ✓ Nothing on the agenda. The project is in a clean state.\n");
+      process.exit(0);
+    }
+
+    for (const sec of sections) {
+      console.log(`${sec.icon} ${sec.title}`);
+      sec.items.forEach(i => console.log(i));
+      console.log(`    → ${sec.next}`);
+      console.log("");
+    }
+
+    console.log(`  ────────────────────`);
+    console.log(`  ${data.totalCount} thing${data.totalCount !== 1 ? 's' : ''} on the agenda. Start with the ${sections[0].icon} row.\n`);
+    process.exit(0);
+  });
+
+program
+  .command("requirement-update")
+  .description("Update one or more requirements (by id, optionally from a JSON file)")
+  .option("-f, --file <path>", "JSON file with updates: { '<requirementId>': { status, epicKey, ... } }")
+  .option("-i, --id <id>", "Single requirement ID to update")
+  .option("--status <status>", "New status (draft/approved/rejected/implemented/tested/superseded)")
+  .option("--epic <key>", "Set epicKey")
+  .option("--sprint <id>", "Set sprintId (use empty string to clear)")
+  .option("--type <type>", "Set type (functional/non-functional)")
+  .option("--title <text>", "Set title")
+  .option("--description <text>", "Set description")
+  .option("--ac <text>", "Set acceptance criteria")
+  .option("--project <id>", "Target project ID (overrides default; requires access to that project)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    let updates = {};
+    if (options.file) {
+      updates = JSON.parse(fs.readFileSync(path.resolve(options.file), "utf8"));
+    } else if (options.id) {
+      const u = {};
+      if (options.status) u.status = options.status;
+      if (options.epic !== undefined) u.epicKey = options.epic;
+      if (options.sprint !== undefined) u.sprintId = options.sprint;
+      if (options.type) u.type = options.type;
+      if (options.title) u.title = options.title;
+      if (options.description) u.description = options.description;
+      if (options.ac) u.acceptanceCriteria = options.ac;
+      updates[options.id] = u;
+    } else {
+      console.error("Provide --file or --id");
+      process.exit(1);
+    }
+
+    const updateReq = httpsCallable(functions, "updateRequirement");
+    let ok = 0, failed = 0;
+    for (const [requirementId, fields] of Object.entries(updates)) {
+      try {
+        await updateReq({ projectId, requirementId, updates: fields });
+        ok++;
+        process.stdout.write(`\r  Updated ${ok}, failed ${failed} / ${Object.keys(updates).length}`);
+      } catch (e) {
+        failed++;
+        console.error(`\nFailed ${requirementId}: ${e.message}`);
+      }
+    }
+    console.log(`\n\nDone. ${ok} updated, ${failed} failed.`);
+    process.exit(0);
+  });
+
 program
   .command("template-upload")
   .description("Upload a test template JSON to the project")
   .requiredOption("-f, --file <path>", "Path to template JSON file")
+  .option("--project <id>", "Target project ID (overrides default)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .action(async (options) => {
     await authenticate(options);
     const creds = getCredentials();
-    if (!creds?.projectId) { console.error("No project configured. Run: qatools setup"); process.exit(1); }
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
 
     const filePath = path.resolve(options.file);
     if (!fs.existsSync(filePath)) { console.error(`File not found: ${filePath}`); process.exit(1); }
@@ -445,7 +998,7 @@ program
     const uploadTemplate = httpsCallable(functions, "uploadTemplate");
     try {
       const result = await uploadTemplate({
-        projectId: creds.projectId,
+        projectId,
         name: data.name,
         version: data.version || "",
         sections: data.sections,
@@ -459,6 +1012,85 @@ program
     process.exit(0);
   });
 
+program
+  .command("backlog-tags")
+  .description("List all existing tags in the backlog")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const listBacklog = httpsCallable(functions, "listBacklog");
+    const result = await listBacklog({ projectId });
+    const tags = new Set();
+    result.data.items.forEach(i => (i.tags || []).forEach(t => tags.add(t)));
+    const sorted = [...tags].sort();
+    if (sorted.length === 0) { console.log("No tags found."); }
+    else { sorted.forEach(t => console.log(t)); console.log(`\n${sorted.length} tag(s)`); }
+    process.exit(0);
+  });
+
+program
+  .command("backlog-duplicates")
+  .description("Find potential duplicate backlog items using AI")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("--local", "Output items for local AI analysis (no API key needed)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    if (options.local) {
+      // Fetch items with full context for local analysis
+      const listBacklog = httpsCallable(functions, "listBacklog");
+      const result = await listBacklog({ projectId });
+      const prefix = t => ({ bug: "AVV", improvement: "IMP", requirement_gap: "GAP", technical_defect: "DEF" }[t] || "BUG");
+      const items = result.data.items.filter(i => i.status !== "rejected");
+      console.log(`Find duplicates among these ${items.length} backlog items. Items that describe the same issue, feature, or task — even if worded differently.\n`);
+      console.log(`Strategy: compare semantically, check shared requirementKey/testId, read comments for context. Would fixing one make the other unnecessary?\n`);
+      for (const i of items) {
+        let line = `${prefix(i.type)}-${i.bugNumber} [${i.type}] (${i.status})`;
+        if (i.requirementKey) line += ` req:${i.requirementKey}`;
+        if (i.testId) line += ` test:${i.testId}`;
+        if (i.tags?.length) line += ` tags:[${i.tags.join(",")}]`;
+        if (i.duplicateOf) line += ` duplicateOf:${i.duplicateOf}`;
+        line += `\n  "${i.description}"`;
+        if (i.comments?.length) line += `\n  Comments: ${i.comments.slice(0, 3).map(c => `"${(c.text || '').substring(0, 100)}"`).join(" | ")}`;
+        console.log(line + "\n");
+      }
+      console.log(`For each duplicate group: items, confidence (high/medium/low), reason.`);
+      process.exit(0);
+    }
+
+    console.log("Analyzing backlog for duplicates...");
+    const findDuplicates = httpsCallable(functions, "findDuplicates");
+    try {
+      const result = await findDuplicates({ projectId });
+      const { duplicates, itemCount } = result.data;
+      console.log(`Analyzed ${itemCount} items.\n`);
+      if (duplicates.length === 0) {
+        console.log("No duplicates found.");
+      } else {
+        for (const group of duplicates) {
+          const conf = group.confidence === 'high' ? '🔴' : group.confidence === 'medium' ? '🟡' : '🟢';
+          console.log(`${conf} ${group.items.join(' ↔ ')} [${group.confidence}]`);
+          console.log(`  ${group.reason}\n`);
+        }
+        console.log(`Found ${duplicates.length} potential duplicate group(s).`);
+      }
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
 program
   .command("backlog-update")
   .description("Update one or more backlog items (JSON file or inline)")
@@ -467,7 +1099,12 @@ program
   .option("--status <status>", "New status")
   .option("--comment <text>", "Add comment")
   .option("--assigned <email>", "Assign to")
-  .option("--tester <email>", "Set tester")
+  .option("--sprint <id>", "Set sprint ID")
+  .option("--priority <n>", "Priority: 1 (high), 2 (medium), 3 (low)")
+  .option("--developer <email>", "Set developer")
+  .option("--requirement-key <key>", "Set requirement key")
+  .option("--tags <tags>", "Set tags (comma-separated, replaces existing)")
+  .option("--description <text>", "Update description")
   .option("--author <name>", "Author name for comments (default: your email)", "Claude")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
@@ -486,7 +1123,12 @@ program
       if (options.status) u.status = options.status;
       if (options.comment) { u.comment = options.comment; u.authorName = options.author; }
       if (options.assigned) u.assignedTo = options.assigned;
-      if (options.tester) u.tester = options.tester;
+      if (options.developer) u.developer = options.developer;
+      if (options.sprint) u.sprintId = options.sprint;
+      if (options.priority) u.priority = parseInt(options.priority, 10);
+      if (options.requirementKey) u.requirementKey = options.requirementKey;
+      if (options.tags) u.tags = options.tags.split(",").map(t => t.trim().toLowerCase());
+      if (options.description) u.description = options.description;
       updates[options.id] = u;
     } else {
       console.error("Provide --file or --id");
@@ -504,15 +1146,703 @@ program
     process.exit(0);
   });
 
+program
+  .command("security-import")
+  .description("Import security scan results (SARIF format) as backlog items")
+  .requiredOption("-f, --file <path>", "Path to SARIF JSON file")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-s, --source <name>", "Scanner name (e.g. semgrep, snyk, sonarqube)")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+
+    const sarif = JSON.parse(fs.readFileSync(path.resolve(options.file), "utf-8"));
+    const importScan = httpsCallable(functions, "importSecurityScan");
+    try {
+      const result = await importScan({ projectId, sarif, source: options.source || "" });
+      const data = result.data;
+      console.log(`\nSecurity scan imported:`);
+      console.log(`  Total findings: ${data.total}`);
+      console.log(`  Created: ${data.created} backlog items`);
+      console.log(`  Skipped: ${data.skipped} (duplicates)`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("context")
+  .description("Show App Context for the project")
+  .option("-o, --output <path>", "Save to JSON file")
+  .option("--project <id>", "Target project ID (overrides default; requires access to that project)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const getCtx = httpsCallable(functions, "getAppContext");
+    const result = await getCtx({ projectId });
+    const ctx = result.data.appContext;
+    if (!ctx) { console.log("No App Context defined for this project."); process.exit(0); }
+    if (options.output) {
+      fs.writeFileSync(path.resolve(options.output), JSON.stringify(ctx, null, 2));
+      console.log(`Saved to ${options.output}`);
+    } else {
+      console.log(`\n${ctx.name}`);
+      if (ctx.description) console.log(ctx.description);
+      if (ctx.stack?.length) {
+        console.log("\nTech Stack:");
+        ctx.stack.forEach(s => console.log(`  ${s.layer}: ${s.technology}${s.version ? ' ' + s.version : ''}${s.notes ? ' — ' + s.notes : ''}`));
+      }
+      if (ctx.architecture) console.log(`\nArchitecture: ${ctx.architecture}`);
+      if (ctx.constraints?.length) { console.log("\nConstraints:"); ctx.constraints.forEach(c => console.log(`  - ${c}`)); }
+      if (ctx.conventions?.length) { console.log("\nConventions:"); ctx.conventions.forEach(c => console.log(`  - ${c.area}: ${c.rule}`)); }
+      if (ctx.sections?.length) { ctx.sections.forEach(s => console.log(`\n${s.title}:\n  ${s.content}`)); }
+    }
+    process.exit(0);
+  });
+
+program
+  .command("context-set")
+  .description("Upload App Context from JSON file")
+  .requiredOption("-f, --file <path>", "Path to App Context JSON file")
+  .option("--project <id>", "Target project ID (overrides default; requires access to that project)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const data = JSON.parse(fs.readFileSync(path.resolve(options.file), "utf8"));
+    const saveCtx = httpsCallable(functions, "saveAppContext");
+    const result = await saveCtx({ projectId, context: data });
+    console.log(`App Context saved (${result.data.id}) — project ${projectId}`);
+    process.exit(0);
+  });
+
+program
+  .command("epics")
+  .description("List epics for the project")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-o, --output <path>", "Save to JSON file")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const listEpics = httpsCallable(functions, "listEpics");
+    const result = await listEpics({ projectId });
+    const epics = result.data.epics;
+    if (options.output) {
+      fs.writeFileSync(path.resolve(options.output), JSON.stringify(epics, null, 2));
+      console.log(`Saved ${epics.length} epics to ${options.output}`);
+    } else {
+      if (epics.length === 0) { console.log("No epics defined."); }
+      else { epics.forEach(e => console.log(`  [${e.key}] ${e.title} (${e.status})`)); }
+    }
+    process.exit(0);
+  });
+
+program
+  .command("epic-update")
+  .description("Update an epic (status, title, description, etc)")
+  .requiredOption("-i, --id <id>", "Epic ID")
+  .option("--status <status>", "draft/active/completed")
+  .option("--title <text>", "Title")
+  .option("--description <text>", "Description")
+  .option("--value <text>", "Value statement")
+  .option("--scope <items>", "Scope items (semicolon-separated, replaces existing)")
+  .option("--priority <n>", "Priority: 1/2/3")
+  .option("--project <id>", "Target project ID")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured."); process.exit(1); }
+    const updates = {};
+    if (options.status) updates.status = options.status;
+    if (options.title) updates.title = options.title;
+    if (options.description) updates.description = options.description;
+    if (options.value) updates.value = options.value;
+    if (options.scope) updates.scope = options.scope.split(";").map(s => s.trim()).filter(s => s);
+    if (options.priority) updates.priority = parseInt(options.priority, 10);
+    if (Object.keys(updates).length === 0) { console.error("No updates provided."); process.exit(1); }
+    const updateEpic = httpsCallable(functions, "updateEpic");
+    try {
+      await updateEpic({ projectId, epicId: options.id, updates });
+      console.log(`Epic ${options.id} updated:`, JSON.stringify(updates));
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("epic-create")
+  .description("Create a new epic")
+  .requiredOption("-k, --key <key>", "Epic key (e.g. auth, billing)")
+  .requiredOption("-t, --title <title>", "Epic title")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-d, --description <text>", "Epic description")
+  .option("--value <text>", "Why this capability exists")
+  .option("--scope <items>", "Scope items (semicolon-separated)")
+  .option("--depends-on <keys>", "Epic keys this depends on (comma-separated)")
+  .option("--priority <n>", "Priority: 1 (high), 2 (medium), 3 (low)", "2")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    const createEpic = httpsCallable(functions, "createEpic");
+    try {
+      const result = await createEpic({
+        projectId,
+        key: options.key,
+        title: options.title,
+        description: options.description || "",
+        value: options.value || "",
+        scope: options.scope ? options.scope.split(";").map(s => s.trim()).filter(s => s) : [],
+        dependsOn: options.dependsOn ? options.dependsOn.split(",").map(s => s.trim()).filter(s => s) : [],
+        priority: parseInt(options.priority, 10),
+      });
+      if (result.data.error === "duplicate") { console.log(`Epic '${options.key}' already exists.`); }
+      else { console.log(`Created epic: ${options.key} (${result.data.id})`); }
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("epic-delete")
+  .description("Delete an epic (only if no requirements are linked)")
+  .requiredOption("-k, --key <key>", "Epic key to delete")
+  .option("--project <id>", "Target project ID (overrides default)")
+  .option("-e, --email <email>", "Login email")
+  .option("-p, --password <password>", "Login password")
+  .action(async (options) => {
+    await authenticate(options);
+    const creds = getCredentials();
+    const projectId = options.project || creds?.projectId;
+    if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
+    // Find epic ID by key
+    const listEpics = httpsCallable(functions, "listEpics");
+    const epicsResult = await listEpics({ projectId });
+    const epic = epicsResult.data.epics.find(e => e.key === options.key);
+    if (!epic) { console.error(`Epic '${options.key}' not found.`); process.exit(1); }
+    const deleteEpic = httpsCallable(functions, "deleteEpic");
+    try {
+      await deleteEpic({ projectId, epicId: epic.id });
+      console.log(`Deleted epic: ${options.key}`);
+    } catch (e) {
+      console.error("Failed:", e.message);
+      process.exit(1);
+    }
+    process.exit(0);
+  });
+
+program
+  .command("init")
+  .description("Initialize QA-Tools in current project (creates skills, CLAUDE.md section)")
+  .option("-k, --api-key <key>", "Claude API key (from QA-Tools → Members → Claude AI Integration)")
+  .action(async (options) => {
+    const cwd = process.cwd();
+    const apiKey = options.apiKey || getCredentials()?.apiKey || "";
+
+    // 1. Create .claude/skills/ directory
+    const skillsDir = path.join(cwd, ".claude", "skills");
+    fs.mkdirSync(skillsDir, { recursive: true });
+    console.log("Created .claude/skills/");
+
+    // 2. Write skills files
+    const skills = {
+      "qa-loop.md": `---
+description: Overview of the QA-Tools delivery loop — from requirement to verified release. Read this first.
+---
+
+# QA-Tools: The Quality Loop
+
+This project uses QA-Tools (https://qa-tools.com) for requirement-driven development.
+
+\`\`\`
+Requirement → Build → Test → Backlog → Fix → Verify
+\`\`\`
+
+## How it works
+
+1. **Requirement defined** — Acceptance criteria (Given/When/Then) and negative scenarios. Each requirement has a semantic key (e.g. \`auth.login-trial\`).
+2. **Feature built** — AI or human implements the feature. Traceable to the requirement via requirementKey.
+3. **Test runs** — Tests are generated from acceptance criteria. Each test links to a requirementKey.
+4. **Backlog updates automatically** — Failed tests create backlog items (bugs). Each item is traceable to requirement, feature, and test.
+5. **AI analyzes and fixes** — AI identifies root cause: is it the code or the requirement? Fixes code or suggests requirement adjustment.
+6. **Retest verifies** — The loop closes only when the requirement is verified.
+
+## CLI quick reference
+
+\`\`\`bash
+# Auth
+qatools login --api-key <key>
+
+# App Context & Epics
+qatools context                      # View app context (stack, architecture, constraints)
+qatools context-set -f context.json  # Upload app context from JSON
+qatools epics                        # List epics
+qatools epic-create -k auth -t "Authentication"  # Create epic
+
+# Requirements
+qatools requirements
+qatools requirements --status approved -o reqs.json
+qatools requirement-keys
+qatools requirement-create -f requirements.json
+
+# Build & backlog
+qatools backlog
+qatools backlog-tags                 # List existing tags (MUST check before tagging)
+qatools backlog-create -d "..." -t bug --requirement-key <key> --assigned <email> --developer <email> --sprint <id> --tags tag1,tag2
+qatools backlog-update -i <id> --status resolved --sprint <id> --priority 1 --requirement-key <key> --developer <email> --tags tag1,tag2
+qatools backlog-duplicates --local   # Output for local AI analysis (no API key needed)
+qatools backlog-duplicates           # AI-powered duplicate detection (requires API key)
+
+# Test
+qatools templates
+qatools template-upload -f tests.json
+qatools pending
+qatools read-session -s <id> -o session.json
+
+# Analyze & fix
+qatools upload-analysis -s <id> -f analysis.json
+
+# Sprints
+qatools sprints
+qatools sprint-items --sprint <id>
+\`\`\`
+
+## Key rules
+- Start with \`qatools context\` to understand the app's tech stack, architecture, and constraints
+- Epics describe capabilities (what + why + scope). Requirements describe testable behaviors. Break down epics by asking: "What must the system do to fulfill this?"
+- A requirement MUST be expressible in Given/When/Then. If it can't → it's an epic or too vague
+- Every requirement MUST link to an epic via epicKey
+- DEPENDENCY HYGIENE: Before creating or modifying epic dependencies, ALWAYS run \`qatools epics\` to review the full dependency graph. Validate: (1) no circular deps, (2) existing deps still make sense, (3) the graph stays minimal — remove deps that are no longer needed. The model evolves — stale dependencies are worse than missing ones.
+- Every test, bug, and fix MUST trace back to a requirementKey
+- Never create duplicate requirements — run \`qatools requirement-keys\` first
+- The loop runs until every requirement is verified
+- BACKLOG = SIGNALS ONLY: AVV (deviation from req), GAP (missing req), DEF (technical issue), IMP (idea). Never create requirements as backlog items. Backlog items are observations — requirements are what you build from.
+- PLANNING FLOW: App Context → Epics → Requirements → Sprint. Backlog feeds back into requirements via GAP/IMP conversion.
+- Tags: ONLY use existing tags — run \`qatools backlog-tags\` first. New tags can only be created by humans in the UI
+- Member roles: developer, tester, project_lead, architect, stakeholder. Stakeholders cannot be assigned items. Use \`--developer <email>\` to set the responsible developer (separate from assignee)
+- Sprint status is automatic: planning/active/overdue/completed based on start and end dates. Only manual actions: complete and reopen
+- Each project has a \`language\` setting (sv/en). Write ALL comments, analyses, and backlog updates in the project's language. Check \`project.language\` in the response from \`qatools read-session\` or \`qatools backlog\`
+- EVIDENCE-FIRST: Never speculate. Every analysis, verdict, and duplicate claim must cite specific evidence (code, test output, error messages, requirement text). If unsure, say so.
+`,
+
+      "qa-requirement-analyst.md": `---
+description: Break down epics into testable requirements. Use when creating or refining requirements from epics.
+---
+
+# QA-Tools: Requirement Analyst
+
+You break down epics into testable requirements with acceptance criteria.
+
+## Intent
+Each epic describes a capability. Your job is to break it down into testable requirements that describe specific behaviors. Ask: "What different things must the system do to fulfill this epic?" — each answer becomes a requirement.
+
+## Workflow
+
+### Step 1: Read epics and app context
+\`qatools context\` — understand the tech stack, architecture, constraints
+\`qatools epics\` — list all epics with their scope
+
+### Step 2: Break down one epic at a time
+For each epic, look at its scope items. Each scope item should become one or more requirements:
+- key (semantic, prefixed with epic key: \`locksmith.create\`, \`locksmith.permissions\`)
+- title — what the system must do
+- description — context and detail
+- acceptanceCriteria (Given/When/Then — ALWAYS)
+- negativeCriteria (ALWAYS — what must NOT happen)
+- epicKey — links to the epic
+- type, priority, category
+
+Upload: \`qatools requirement-create -f <epic>-requirements.json\`
+Wait for approval before next epic.
+
+### Step 3: Handle feedback
+\`qatools requirements --status rejected\`
+Improve rejected requirements and re-upload.
+
+## Rules
+- A requirement MUST be expressible in Given/When/Then. If it can't, it's either an epic (too broad) or too vague (needs clarification)
+- A requirement describes a TESTABLE BEHAVIOR, not a UI element or implementation detail
+- ALWAYS Given/When/Then format
+- ALWAYS include negative scenarios
+- Every requirement MUST link to an epic via epicKey
+- One epic at a time — get approval before continuing
+- Run \`qatools requirement-keys\` before creating to avoid duplicates
+- EVIDENCE-FIRST: base requirements on observable behavior, not assumptions
+- Before creating new epics: run \`qatools epics\` and review the dependency graph. Remove stale dependencies. Keep the model clean — it evolves over time.
+`,
+
+      "qa-developer.md": `---
+description: Implement features based on approved requirements. Use when building new functionality.
+---
+
+# QA-Tools: Developer
+
+You implement code based on approved requirements from QA-Tools.
+
+## The model
+
+\\\`\\\`\\\`
+App Context → Epics → Requirements → Sprint → Implementation → Test
+                                        ↑
+                              Backlog (signals only)
+\\\`\\\`\\\`
+
+- **Requirements** drive what you build. They come from epics.
+- **Backlog** is NOT your task list. It contains observations: AVV (deviations), GAP (missing reqs), DEF (technical defects), IMP (improvement ideas).
+- You build from REQUIREMENTS, not backlog items.
+
+## Workflow
+
+1. Read app context and current sprint:
+   \`qatools context\`
+   \`qatools requirements --status approved -o requirements.json\`
+
+2. Implement according to acceptanceCriteria AND negativeCriteria.
+   Every piece of code must be traceable to a requirementKey.
+
+3. If you discover something unexpected during implementation:
+   - Behavior doesn't match a requirement → create AVV: \`qatools backlog-create -d "..." -t bug --requirement-key <key>\`
+   - Requirement is missing or unclear → create GAP: \`qatools backlog-create -d "..." -t requirement_gap --requirement-key <key>\`
+   - Technical issue (infra, runtime) → create DEF: \`qatools backlog-create -d "..." -t technical_defect\`
+   - Improvement idea → create IMP: \`qatools backlog-create -d "..." -t improvement\`
+
+4. NEVER create requirements directly as backlog items. If a GAP needs to become a requirement, flag it — the user decides.
+
+5. Check for pending test sessions:
+   \`qatools pending\`
+   \`qatools read-session -s <id> -o session.json\`
+
+6. If tests fail, analyze and fix:
+   \`qatools upload-analysis -s <id> -f analysis.json\`
+
+## Rules
+- Build from REQUIREMENTS, not backlog
+- Backlog items are SIGNALS — observations during work, not tasks to implement
+- Implement EXACTLY what the requirement says — ask if unclear
+- If the requirement is ambiguous, create a GAP — don't guess
+- Include commitId when uploading analysis
+`,
+
+      "qa-test-generator.md": `---
+description: Generate test protocols from approved requirements. Use after requirements are approved.
+---
+
+# QA-Tools: Test Generator
+
+You generate test protocols (templates) from approved requirements.
+
+## Workflow
+
+1. Fetch approved requirements:
+   \`qatools requirements --status approved -o requirements.json\`
+
+2. Check existing keys:
+   \`qatools requirement-keys\`
+
+3. Generate test JSON. Each test must have:
+   - id (prefix + section.number, e.g. P-1.1)
+   - requirementKey (links to the requirement)
+   - requirementVersion (e.g. "1.0")
+   - purpose (what this test verifies — locked in session)
+   - name, steps, expected
+
+4. Upload:
+   \`qatools template-upload -f test-protocol.json\`
+
+## JSON format
+\`\`\`json
+{
+  "name": "Test Protocol v1.0",
+  "sections": [{
+    "title": "1. Authentication",
+    "tests": [{
+      "id": "P-1.1",
+      "requirementKey": "auth.login-trial",
+      "requirementVersion": "1.0",
+      "purpose": "Verifies trial account login per acceptance criteria",
+      "name": "Login with trial account",
+      "steps": "1. Go to /login\n2. Click Try free\n3. Enter test@example.com",
+      "expected": "User logged in, redirected to dashboard"
+    }]
+  }]
+}
+\`\`\`
+
+## Rules
+- Every test MUST have requirementKey, requirementVersion, and purpose
+- Generate from BOTH acceptance criteria AND negative scenarios
+`,
+
+      "qa-test-analyst.md": `---
+description: Analyze failed test sessions and fix bugs. Use when test sessions are pending analysis.
+---
+
+# QA-Tools: Test Analyst
+
+You analyze test sessions and fix bugs found during testing.
+
+## Workflow
+
+1. Check for pending sessions:
+   \`qatools pending\`
+
+2. Read session details:
+   \`qatools read-session -s <id> -o session.json\`
+
+3. For each FAILED test:
+   - Analyze root cause: is it the code or the requirement?
+   - Determine verdict: bugg, troligen-db, testprotokoll, design, ux, ej-aktuell, kräver-genomgång
+   - Fix the bug if possible (fixStatus: "fixed", list filesChanged)
+   - If the requirement is wrong, set verdict to "testprotokoll"
+
+4. Upload analysis:
+   \`qatools upload-analysis -s <id> -f analysis.json\`
+
+5. Update backlog items:
+   \`qatools backlog-update -f updates.json\`
+
+## Analysis JSON format
+\`\`\`json
+{
+  "sessionId": "<id>",
+  "results": {
+    "P-1.6": {
+      "verdict": "bugg",
+      "comment": "Race condition — auth0Id never set",
+      "fixStatus": "fixed",
+      "commitId": "a1b2c3d",
+      "filesChanged": ["AuthService.cs", "OpenController.cs"]
+    }
+  }
+}
+\`\`\`
+
+## Rules
+- EVIDENCE-FIRST: Base every verdict and comment on observable evidence. Cite specific code, test steps, or error messages. Never speculate.
+- Always identify whether the problem is in the code or the requirement
+- If you fix code, list all changed files and include the commitId (short hash from \`git rev-parse --short HEAD\`)
+- When creating backlog items from test failures, use the correct type:
+  - Code violates requirement → AVV (bug): \`qatools backlog-create -t bug -d "..." --requirement-key <key>\`
+  - Requirement missing/unclear → GAP: \`qatools backlog-create -t requirement_gap -d "..." --requirement-key <key>\`
+  - Technical/runtime issue → DEF: \`qatools backlog-create -t technical_defect -d "..."\`
+- NEVER create requirements as backlog items — backlog is for signals only
+`,
+
+      "qa-release-manager.md": `---
+description: Manage sprints, backlog, and release readiness. Use for sprint planning and release verification.
+---
+
+# QA-Tools: Release Manager
+
+You manage sprints, backlog, and verify release readiness.
+
+## Workflow
+
+1. Review sprints:
+   \`qatools sprints\`
+   \`qatools sprint-items --sprint <id> -o sprint.json\`
+
+2. Break down requirements into stories/tasks:
+   \`qatools backlog-create -d "Implement login flow" -t story --requirement-key auth.login-trial\`
+
+3. Track progress:
+   \`qatools backlog --sprint <id>\`
+   \`qatools backlog-update -i <id> --status resolved\`
+
+4. Verify requirement coverage:
+   \`qatools requirements --status approved\`
+   Ensure every approved requirement has tests and all tests pass.
+
+5. Release when every requirement in the sprint is verified.
+
+## Rules
+- A sprint is ready ONLY when all requirements are verified
+- Every backlog item must link to a requirementKey
+- Track: requirement → test → bug → fix → retest → verified
+`,
+      "qa-evidence-first.md": `---
+description: Core principle — never speculate, always cite evidence. Applies to ALL work.
+---
+
+# Evidence-First Principle
+
+This is a non-negotiable rule for all AI work in this project.
+
+## The rule
+Every claim, verdict, analysis, and recommendation MUST cite specific evidence:
+- Code references (file, function, line)
+- Test output (actual vs expected)
+- Error messages (exact text)
+- Requirement text (quote the GWT)
+
+## What this means in practice
+
+### When analyzing test failures
+❌ "This is probably a timing issue"
+✅ "AuthService.cs:42 sets auth0Id after the response is sent (line 45), causing a race condition. Test P-1.6 expects auth0Id to be set before redirect."
+
+### When creating backlog items
+❌ "Login seems broken"
+✅ "Given a user with valid credentials, When clicking login, Then the response is 500. Error: 'NullReferenceException at AuthController.cs:78'. Requirement auth.login expects redirect to dashboard."
+
+### When suggesting fixes
+❌ "Try adding a null check"
+✅ "auth0Id is null because createUserResponse (line 42) is awaited but its result is not assigned. Fix: \`var user = await createUserResponse;\` then \`auth0Id = user.Id;\`"
+
+### When flagging requirement issues
+❌ "This requirement is unclear"
+✅ "Requirement auth.login says 'user is redirected' but doesn't specify WHERE. The test expects /dashboard but the code redirects to /home."
+
+## If you're unsure
+Say "I'm unsure" — that's better than guessing. Suggest what evidence would resolve the uncertainty.
+`
+    };
+
+    for (const [filename, content] of Object.entries(skills)) {
+      fs.writeFileSync(path.join(skillsDir, filename), content);
+    }
+    console.log("  ✓ qa-loop.md (start here)");
+    console.log("  ✓ qa-requirement-analyst.md");
+    console.log("  ✓ qa-developer.md");
+    console.log("  ✓ qa-test-generator.md");
+    console.log("  ✓ qa-test-analyst.md");
+    console.log("  ✓ qa-release-manager.md");
+    console.log("  ✓ qa-evidence-first.md");
+
+    // 4. Generate app context skill from API
+    try {
+      await authenticate(options);
+      const creds = getCredentials();
+      if (creds?.projectId) {
+        const getCtx = httpsCallable(functions, "getAppContext");
+        const ctxResult = await getCtx({ projectId: creds.projectId });
+        const ctx = ctxResult.data.appContext;
+        if (ctx) {
+          let ctxSkill = `---\ndescription: App-specific context for ${ctx.name}. Auto-generated from QA-Tools App Context.\n---\n\n# ${ctx.name}\n\n`;
+          if (ctx.purpose) ctxSkill += `## Purpose\n${ctx.purpose}\n\n`;
+          if (ctx.domainObjects?.length) ctxSkill += `## Domain Objects\n${ctx.domainObjects.map(d => '- ' + d).join('\n')}\n\n`;
+          if (ctx.actors?.length) ctxSkill += `## Actors\n${ctx.actors.map(a => '- ' + a).join('\n')}\n\n`;
+          if (ctx.stack?.length) ctxSkill += `## Tech Stack\n${ctx.stack.map(s => '- **' + s.layer + ':** ' + s.technology + (s.version ? ' ' + s.version : '') + (s.notes ? ' — ' + s.notes : '')).join('\n')}\n\n`;
+          if (ctx.architecture) ctxSkill += `## Architecture\n${ctx.architecture}\n\n`;
+          if (ctx.security?.length) ctxSkill += `## Security\n${ctx.security.map(s => '- ' + s).join('\n')}\n\n`;
+          if (ctx.aiRules?.length) ctxSkill += `## AI Rules\n${ctx.aiRules.map(r => '- ' + r).join('\n')}\n\n`;
+          if (ctx.conventions?.length) ctxSkill += `## Design Principles\n${ctx.conventions.map(c => '- **' + c.area + ':** ' + c.rule).join('\n')}\n\n`;
+          if (ctx.constraints?.length) ctxSkill += `## Constraints\n${ctx.constraints.map(c => '- ' + c).join('\n')}\n\n`;
+          fs.writeFileSync(path.join(skillsDir, "app-context.md"), ctxSkill);
+          console.log("  ✓ app-context.md (from project)");
+
+          // Generate custom skills from App Context
+          if (ctx.skills?.length) {
+            for (const skill of ctx.skills) {
+              const fname = skill.filename.endsWith('.md') ? skill.filename : skill.filename + '.md';
+              const content = `---\ndescription: ${skill.title}\n---\n\n# ${skill.title}\n\n${skill.content}\n`;
+              fs.writeFileSync(path.join(skillsDir, fname), content);
+              console.log("  ✓ " + fname + " (custom)");
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // No auth or no context — skip, not critical
+    }
+
+    // 3. Update or create CLAUDE.md
+    const claudeMdPath = path.join(cwd, "CLAUDE.md");
+    const qaSection = `
+## QA-Tools Integration
+
+\`\`\`bash
+export QATOOLS_API_KEY=${apiKey || "<din-nyckel>"}
+\`\`\`
+
+### Kommandon
+- \`qatools requirements\` — lista krav
+- \`qatools backlog\` — lista backlog
+- \`qatools pending\` — väntande testsessioner
+- \`qatools read-session -s <id>\` — läs session
+- \`qatools upload-analysis -s <id> -f analysis.json\` — ladda upp analys
+- \`qatools requirement-create -f file.json\` — skapa krav
+- \`qatools template-upload -f file.json\` — ladda upp testprotokoll
+- \`qatools backlog-create -d "..." -t task\` — skapa ärende
+- \`qatools backlog-update -i <id> --status resolved\` — uppdatera
+
+### Roller (skills)
+Se \`.claude/skills/\` för instruktioner per roll.
+`;
+
+    if (fs.existsSync(claudeMdPath)) {
+      const existing = fs.readFileSync(claudeMdPath, "utf8");
+      if (!existing.includes("QA-Tools Integration")) {
+        fs.appendFileSync(claudeMdPath, "\n" + qaSection);
+        console.log("\n✓ Added QA-Tools section to CLAUDE.md");
+      } else {
+        console.log("\n⚠ CLAUDE.md already has QA-Tools section (skipped)");
+      }
+    } else {
+      fs.writeFileSync(claudeMdPath, "# Project\n" + qaSection);
+      console.log("\n✓ Created CLAUDE.md with QA-Tools section");
+    }
+
+    console.log("\n🎉 QA-Tools initialized! Claude is ready.");
+    if (!apiKey) console.log("\n⚠ No API key set. Add it to CLAUDE.md: export QATOOLS_API_KEY=<key>");
+    process.exit(0);
+  });
+
 program
   .command("login")
   .description("Save credentials to ~/.qatools (email/password or --google)")
   .option("-e, --email <email>", "Login email")
   .option("-p, --password <password>", "Login password")
   .option("-g, --google", "Login with Google (opens browser)")
+  .option("-k, --api-key <key>", "Login with Claude API key (permanent, no browser)")
   .action(async (options) => {
     const configPath = path.join(process.env.HOME || process.env.USERPROFILE, ".qatools");
 
+    if (options.apiKey) {
+      // API key login — no browser, no expiry
+      console.log("Authenticating with API key...");
+      const authRes = await fetch("https://us-central1-qatools-app.cloudfunctions.net/authenticateWithApiKey", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ data: { apiKey: options.apiKey } }),
+      });
+      const authData = await authRes.json();
+      if (authData.error || !authData.result) {
+        console.error("Invalid API key.");
+        process.exit(1);
+      }
+      const { customToken, projectId, projectName, email } = authData.result;
+      // Save config
+      const config = { apiKey: options.apiKey, projectId, projectName, email };
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+      console.log(`Logged in as Claude for project: ${projectName}`);
+      console.log(`Project ID: ${projectId}`);
+      process.exit(0);
+    }
+
     if (options.google) {
       // Google login via browser
       console.log("Opening browser for Google sign-in...\n");