@qulib/core 0.4.3 → 0.5.1

package/README.md

@@ -277,6 +277,107 @@ npm run analyze -- --url https://example.com --ephemeral > report.bundle.json
 npm run clean
 ```
 
+## Minimum config
+
+Smallest legal `qulib.config.ts`:
+
+```ts
+import type { HarnessConfig } from './src/schemas/config.schema.js';
+
+const config: HarnessConfig = {
+  maxPagesToScan: 20,
+  maxDepth: 3,
+  timeoutMs: 30000,
+};
+
+export default config;
+```
+
+All other fields inherit from schema defaults or CLI/runtime defaults.
+
+## Scan walkthroughs (copy-paste)
+
+### 1) Public scan
+
+```bash
+npx @qulib/core analyze --url https://yourapp.com
+```
+
+### 2) Auth-blocked scan (honest blocked mode)
+
+```bash
+npx @qulib/core analyze --url https://yourapp.com/auth
+```
+
+When auth blocks access and no auth config is supplied, Qulib reports `status: "blocked"` (or `partial` if it could still crawl some public pages). This is intentional honesty, not a failure mode.
+
+### 3) Authenticated scan with storage state
+
+```bash
+# Capture once (manual OAuth/SSO-safe flow)
+qulib auth init --base-url https://yourapp.com
+
+# Reuse saved session
+qulib analyze --url https://yourapp.com --auth-storage-state ./qulib-storage-state.json
+```
+
+## Sample report (fixture baseline)
+
+From the local fixture baseline used in v0.5.0 PR 1/2:
+
+```json
+{
+  "status": "complete",
+  "releaseConfidence": 68,
+  "gaps": [
+    "... 4 total gap items ..."
+  ]
+}
+```
+
+Use these as conservative reference numbers:
+- public fixture (`/`): `releaseConfidence: 68/100`, `gaps: 4`
+- auth-wall fixture (`/auth`): `releaseConfidence: 24/100`, `gaps: 2`
+- broken fixture (`/broken`): `releaseConfidence: 0/100`, `gaps: 6`
+
+## MCP tools quick map
+
+| Tool | When to use | Key input |
+|---|---|---|
+| `analyze_app` | Main QA scan for release confidence + gaps | `url`, optional `auth`, optional LLM knobs |
+| `detect_auth` | Fast single-pass auth pattern guess | `url`, optional `timeoutMs` |
+| `explore_auth` | Deeper auth-path discovery on unfamiliar apps | `url`, optional `timeoutMs` |
+| `qulib_score_automation` | Score local repo automation maturity | absolute `repoPath`, optional `includeFullDimensions` |
+
+## Output directories
+
+Qulib writes runtime artifacts to:
+
+- `.scan-state/` — intermediate state (discovered routes, gap analysis snapshots, decision log)
+- `output/` — final `report.json` and `report.md`
+
+Both are gitignored and safe to delete; Qulib recreates them on the next non-ephemeral run.
+
+## ANTHROPIC_API_KEY (LLM scenarios)
+
+For MCP-hosted usage, set `ANTHROPIC_API_KEY` in your host's `env` block:
+
+```json
+{
+  "mcpServers": {
+    "qulib": {
+      "command": "npx",
+      "args": ["@qulib/mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}
+```
+
+Without this key, Qulib still runs deterministic checks (crawl, a11y, links, console, scoring) and falls back to template scenarios instead of LLM-generated ones.
+
 ## Playwright browsers
 
 ```bash

package/dist/__tests__/cli-smoke-fixture.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-smoke-fixture.d.ts.map

package/dist/__tests__/cli-smoke-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-smoke-fixture.d.ts","sourceRoot":"","sources":["../../src/__tests__/cli-smoke-fixture.ts"],"names":[],"mappings":""}

package/dist/__tests__/cli-smoke-fixture.js

@@ -0,0 +1,58 @@
+/**
+ * Offline CLI smoke: spawn `node bin/qulib.js analyze --url <fixture>` against
+ * the local fixture server and assert the CLI exited 0. Runnable script (not a
+ * node:test file) — invoked in CI by `node --import tsx/esm src/__tests__/cli-smoke-fixture.ts`.
+ *
+ * Removes the live `https://example.com` dependency from CI's smoke-test-cli job.
+ *
+ * The fixture server runs in this process; the CLI is spawned as a child. We use
+ * async `spawn` (not `spawnSync`) so the parent event loop stays free to serve
+ * the child's HTTP requests against the fixture.
+ */
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { startFixtureServer } from './fixture-server.js';
+const __dir = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(__dir, '../../bin/qulib.js');
+function runCli(url) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('node', [cliPath, 'analyze', '--url', url, '--ephemeral'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            rejectPromise(new Error('CLI smoke timed out after 120s'));
+        }, 120_000);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            rejectPromise(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolvePromise({
+                exitCode: code ?? -1,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8'),
+            });
+        });
+    });
+}
+function assertCliPassed(result) {
+    if (result.exitCode !== 0) {
+        throw new Error(`CLI exited with code ${result.exitCode}\n--- stdout ---\n${result.stdout}\n--- stderr ---\n${result.stderr}`);
+    }
+}
+const handle = await startFixtureServer();
+try {
+    const result = await runCli(`${handle.baseUrl}/`);
+    assertCliPassed(result);
+    console.log('[cli-smoke] ✔ CLI exited 0 against fixture public surface');
+}
+finally {
+    await handle.close();
+}

package/dist/__tests__/fixture-server.d.ts

@@ -0,0 +1,6 @@
+export interface FixtureServerHandle {
+    baseUrl: string;
+    close: () => Promise<void>;
+}
+export declare function startFixtureServer(): Promise<FixtureServerHandle>;
+//# sourceMappingURL=fixture-server.d.ts.map

package/dist/__tests__/fixture-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-server.d.ts","sourceRoot":"","sources":["../../src/__tests__/fixture-server.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAyGD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,mBAAmB,CAAC,CA0CvE"}

package/dist/__tests__/fixture-server.js

@@ -0,0 +1,141 @@
+/**
+ * Deterministic Node.js fixture server for offline Qulib integration tests.
+ *
+ * Serves the static HTML files in `packages/core/fixtures/` over loopback so
+ * the test suite never depends on a live website. Used by
+ * `analyze.fixtures.test.ts` and any future offline integration coverage.
+ *
+ * Never imported by product code. Helpers are private to this module; only
+ * `startFixtureServer` and `FixtureServerHandle` are exported.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+const TEXT_CONTENT_TYPE = 'text/plain; charset=utf-8';
+function resolveFixturesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '../../fixtures');
+}
+function routeToFile(pathname) {
+    if (pathname.includes('..'))
+        return null;
+    const fixturesDir = resolveFixturesDir();
+    if (pathname === '/' || pathname === '/index.html') {
+        return join(fixturesDir, 'public/index.html');
+    }
+    if (pathname === '/about') {
+        return join(fixturesDir, 'public/about.html');
+    }
+    if (pathname === '/features') {
+        return join(fixturesDir, 'public/features.html');
+    }
+    if (pathname === '/docs') {
+        return join(fixturesDir, 'public/index.html');
+    }
+    if (pathname === '/auth') {
+        return join(fixturesDir, 'auth-wall/index.html');
+    }
+    if (pathname === '/authenticated' || pathname.startsWith('/authenticated/')) {
+        return join(fixturesDir, 'authenticated/index.html');
+    }
+    if (pathname === '/broken') {
+        return join(fixturesDir, 'broken/index.html');
+    }
+    return null;
+}
+async function readFixture(filePath) {
+    return readFile(filePath);
+}
+function respond(res, status, body, contentType) {
+    const buf = typeof body === 'string' ? Buffer.from(body, 'utf8') : body;
+    res.writeHead(status, {
+        'Content-Type': contentType,
+        'Content-Length': buf.length,
+        'Cache-Control': 'no-store',
+    });
+    res.end(buf);
+}
+function respondNotFound(res) {
+    respond(res, 404, 'Not found', TEXT_CONTENT_TYPE);
+}
+function respondServerError(res, message) {
+    respond(res, 500, `Fixture server error: ${message}`, TEXT_CONTENT_TYPE);
+}
+function respondMethodNotAllowed(res) {
+    res.writeHead(405, {
+        Allow: 'GET',
+        'Content-Type': TEXT_CONTENT_TYPE,
+        'Cache-Control': 'no-store',
+    });
+    res.end('Method Not Allowed');
+}
+async function handleRequest(req, res) {
+    try {
+        if (req.method !== 'GET') {
+            respondMethodNotAllowed(res);
+            return;
+        }
+        const rawUrl = req.url ?? '/';
+        let pathname;
+        try {
+            pathname = new URL(rawUrl, 'http://127.0.0.1').pathname;
+        }
+        catch {
+            respondNotFound(res);
+            return;
+        }
+        const filePath = routeToFile(pathname);
+        if (filePath === null) {
+            respondNotFound(res);
+            return;
+        }
+        const body = await readFixture(filePath);
+        respond(res, 200, body, HTML_CONTENT_TYPE);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        respondServerError(res, message);
+    }
+}
+export async function startFixtureServer() {
+    const fixturesDir = resolveFixturesDir();
+    try {
+        const s = await stat(fixturesDir);
+        if (!s.isDirectory()) {
+            throw new Error(`fixtures path is not a directory: ${fixturesDir}`);
+        }
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Fixture directory not found at ${fixturesDir}: ${detail}`);
+    }
+    const server = createServer((req, res) => {
+        void handleRequest(req, res);
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.once('error', rejectPromise);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', rejectPromise);
+            resolvePromise();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        server.close();
+        throw new Error('Fixture server did not return a usable address after listen');
+    }
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+    return {
+        baseUrl,
+        close: () => new Promise((resolvePromise, rejectPromise) => {
+            server.close((err) => {
+                if (err)
+                    rejectPromise(err);
+                else
+                    resolvePromise();
+            });
+        }),
+    };
+}

package/dist/cli/auth-login-resolve.js

@@ -29,7 +29,7 @@ export function parseCredentialsJsonString(json) {
     return out;
 }
 export function resolveFormLoginPath(baseUrl, authOptions, authPathId) {
-    const formPaths = (authOptions ?? []).filter((o) => o.type === 'form-login' && o.requirements.method === 'credentials');
+    const formPaths = (authOptions ?? []).filter((o) => (o.type === 'form-login' || o.type === 'form-multi') && o.requirements.method === 'credentials');
     if (formPaths.length === 0) {
         throw new Error(`No automatable form-login path detected on ${baseUrl}. Use \`qulib auth init\` for manual login.`);
     }

package/dist/cli/auth-login-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-login-run.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAsB5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEhE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoIhB"}
+{"version":3,"file":"auth-login-run.d.ts","sourceRoot":"","sources":["../../src/cli/auth-login-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAsB5D,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAMhE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoIhB"}

package/dist/cli/auth-login-run.js

@@ -16,7 +16,9 @@ function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 export function authPathNeedsClickReveal(path) {
-    return path.type === 'form-login' && path.source === 'heuristic' && !builtInOAuthIds.has(path.id);
+    return ((path.type === 'form-login' || path.type === 'form-multi') &&
+        (path.source === 'heuristic' || path.source === 'user-local') &&
+        !builtInOAuthIds.has(path.id));
 }
 export async function runAutomatedAuthLogin(params) {
     const { chromium } = await import('@playwright/test');

package/dist/cli/index.js

@@ -98,6 +98,7 @@ async function runAnalyze(options) {
         repoPath: options.repo,
         config,
         writeArtifacts,
+        skipAuthDetection: options.skipAuthDetection,
     });
     if (ephemeral) {
         console.log(JSON.stringify({
@@ -157,6 +158,7 @@ program
     .option('--config <file>', 'Path to config file (relative to cwd)', 'qulib.config.ts')
     .option('--adapter <type>', 'Override default test adapter (playwright, cypress-e2e, cypress-component, api)', 'playwright')
     .option('--ephemeral', 'Do not write to disk — return full report as JSON on stdout (use for MCP/CI)', false)
+    .option('--skip-auth-detection', 'Crawl the public surface even if auth is detected (useful for sites with sign-in CTAs on public pages)', false)
     .option('--auth-storage-state <path>', 'Path to a storage state JSON file (use after `qulib auth init`)')
     .option('--auth-form-login', 'Use form-login; requires --login-url, credentials, and selectors', false)
     .option('--login-url <url>', 'Form login page URL (required with --auth-form-login)')
@@ -179,6 +181,7 @@ program
         repo: options.repo,
         configFile: options.config,
         ephemeral: options.ephemeral,
+        skipAuthDetection: Boolean(options.skipAuthDetection),
         authStorageState: options.authStorageState,
         authFormLogin,
         loginUrl,

package/dist/llm/providers/anthropic.js

@@ -1,5 +1,5 @@
 import { emitTelemetry } from '../../telemetry/emit.js';
-const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
 function estimateTokensFromChars(chars) {
     return Math.max(0, Math.ceil(chars / 4));
 }

package/dist/phases/think-finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"think-finalize.d.ts","sourceRoot":"","sources":["../../src/phases/think-finalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAA4C,KAAK,WAAW,EAAwB,MAAM,mCAAmC,CAAC;AAQrI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;AAEtG,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,EACzD,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,GAAG,mBAAmB,GAAG,MAAM,CAAC,GAC9F,OAAO,CAAC,WAAW,CAAC,CAiLtB"}
+{"version":3,"file":"think-finalize.d.ts","sourceRoot":"","sources":["../../src/phases/think-finalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACnG,OAAO,EAA4C,KAAK,WAAW,EAAwB,MAAM,mCAAmC,CAAC;AAQrI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;AAEtG,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,EACzD,WAAW,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,GAAG,mBAAmB,GAAG,MAAM,CAAC,GAC9F,OAAO,CAAC,WAAW,CAAC,CAuLtB"}

package/dist/phases/think-finalize.js

@@ -87,7 +87,13 @@ export async function finalizeGapAnalysisFromDraft(draft, config, artifacts = {
                     : undefined,
             });
             try {
-                const parsed = JSON.parse(llmResult.text);
+                // Claude 4 models wrap JSON in markdown fences despite instructions.
+                // Strip ```json ... ``` or ``` ... ``` before parsing.
+                const rawText = llmResult.text.trim();
+                const stripped = rawText.replace(/^```(?:json)?\s*\n?/i, '').replace(/\n?```\s*$/i, '').trim();
+                // Also handle models that embed the array mid-prose — grab first [...] block
+                const jsonText = stripped.startsWith('[') ? stripped : (stripped.match(/\[[\s\S]*\]/)?.[0] ?? stripped);
+                const parsed = JSON.parse(jsonText);
                 const candidates = Array.isArray(parsed) ? parsed : [];
                 for (const item of candidates) {
                     const validated = NeutralScenarioSchema.safeParse(item);

package/dist/schemas/automation-maturity.schema.d.ts

@@ -27,6 +27,7 @@ export declare const AutomationMaturityDimensionSchema: z.ZodObject<{
     recommendations: z.ZodArray<z.ZodString, "many">;
     applicability: z.ZodOptional<z.ZodEnum<["applicable", "not_applicable", "unknown"]>>;
     reason: z.ZodOptional<z.ZodString>;
+    guidance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     recommendations: string[];
     dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -35,6 +36,7 @@ export declare const AutomationMaturityDimensionSchema: z.ZodObject<{
     evidence: string[];
     reason?: string | undefined;
     applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+    guidance?: string | undefined;
 }, {
     recommendations: string[];
     dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -43,6 +45,7 @@ export declare const AutomationMaturityDimensionSchema: z.ZodObject<{
     evidence: string[];
     reason?: string | undefined;
     applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+    guidance?: string | undefined;
 }>;
 export declare const AutomationMaturitySchema: z.ZodObject<{
     computedAt: z.ZodString;
@@ -58,6 +61,7 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         recommendations: z.ZodArray<z.ZodString, "many">;
         applicability: z.ZodOptional<z.ZodEnum<["applicable", "not_applicable", "unknown"]>>;
         reason: z.ZodOptional<z.ZodString>;
+        guidance: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         recommendations: string[];
         dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -66,6 +70,7 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         evidence: string[];
         reason?: string | undefined;
         applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+        guidance?: string | undefined;
     }, {
         recommendations: string[];
         dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -74,6 +79,7 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         evidence: string[];
         reason?: string | undefined;
         applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+        guidance?: string | undefined;
     }>, "many">;
     topRecommendations: z.ZodArray<z.ZodString, "many">;
     scoreFormula: z.ZodOptional<z.ZodString>;
@@ -91,6 +97,7 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         evidence: string[];
         reason?: string | undefined;
         applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+        guidance?: string | undefined;
     }[];
     topRecommendations: string[];
     scoreFormula?: string | undefined;
@@ -108,6 +115,7 @@ export declare const AutomationMaturitySchema: z.ZodObject<{
         evidence: string[];
         reason?: string | undefined;
         applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+        guidance?: string | undefined;
     }[];
     topRecommendations: string[];
     scoreFormula?: string | undefined;

package/dist/schemas/automation-maturity.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/automation-maturity.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qCAAqC,wDAIhD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;EAe5C,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASnC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AACpG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"automation-maturity.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/automation-maturity.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qCAAqC,wDAIhD,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB5C,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASnC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AACpG,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/schemas/automation-maturity.schema.js

@@ -38,6 +38,7 @@ export const AutomationMaturityDimensionSchema = z.object({
     recommendations: z.array(z.string()),
     applicability: AutomationMaturityApplicabilitySchema.optional(),
     reason: z.string().optional(),
+    guidance: z.string().optional(),
 });
 export const AutomationMaturitySchema = z.object({
     computedAt: z.string().datetime(),

package/dist/schemas/repo-analysis.schema.d.ts

@@ -163,6 +163,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             recommendations: z.ZodArray<z.ZodString, "many">;
             applicability: z.ZodOptional<z.ZodEnum<["applicable", "not_applicable", "unknown"]>>;
             reason: z.ZodOptional<z.ZodString>;
+            guidance: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             recommendations: string[];
             dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -171,6 +172,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }, {
             recommendations: string[];
             dimension: "test-coverage-breadth" | "framework-adoption" | "test-id-hygiene" | "ci-integration" | "auth-test-coverage" | "component-test-ratio";
@@ -179,6 +181,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }>, "many">;
         topRecommendations: z.ZodArray<z.ZodString, "many">;
         scoreFormula: z.ZodOptional<z.ZodString>;
@@ -196,6 +199,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }[];
         topRecommendations: string[];
         scoreFormula?: string | undefined;
@@ -213,6 +217,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }[];
         topRecommendations: string[];
         scoreFormula?: string | undefined;
@@ -262,6 +267,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }[];
         topRecommendations: string[];
         scoreFormula?: string | undefined;
@@ -311,6 +317,7 @@ export declare const RepoAnalysisSchema: z.ZodObject<{
             evidence: string[];
             reason?: string | undefined;
             applicability?: "unknown" | "applicable" | "not_applicable" | undefined;
+            guidance?: string | undefined;
         }[];
         topRecommendations: string[];
         scoreFormula?: string | undefined;

package/dist/schemas/repo-analysis.schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-analysis.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/repo-analysis.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,8BAA8B,8HAUzC,CAAC;AAEH,eAAO,MAAM,kCAAkC,sCAAoC,CAAC;AAEpF,eAAO,MAAM,2BAA2B,0FAOtC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;EAKnC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;EAIzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;EASjC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"version":3,"file":"repo-analysis.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/repo-analysis.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,8BAA8B,8HAUzC,CAAC;AAEH,eAAO,MAAM,kCAAkC,sCAAoC,CAAC;AAEpF,eAAO,MAAM,2BAA2B,0FAOtC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;EAKnC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AACtF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;EAIzB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;EASjC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/tools/auth/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAsQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,yBAAyB,GACzB,iBAAiB,GACjB,SAAS,CAAC;AAEd,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAwQD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,4BAA4B,CA6B/B;AAOD,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAgD9C;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,SAAS,SAAQ,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAelD;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAQ,GAChB,OAAO,CAAC,4BAA4B,CAAC,CAyDvC;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAqJvB"}

package/dist/tools/auth/detect.js

@@ -151,7 +151,7 @@ function authPathsFromOauthButtons(oauthButtons, loginUrl) {
 }
 async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, timeoutMs, progress) {
     const out = [];
-    const buttons = page.locator('button');
+    const buttons = page.locator('button, [role="button"]');
     const n = await buttons.count();
     const seenLabels = new Set();
     const SUBMIT_RE = /^(sign in|log in|submit|continue|next|cancel|close)$/i;
@@ -207,8 +207,9 @@ async function probeClickToRevealForms(page, loginUrl, alreadyMatchedTexts, time
             await waitNetworkIdleBestEffort(page);
             continue;
         }
+        await waitNetworkIdleBestEffort(page);
         try {
-            await page.locator('input[type="password"]:visible').first().waitFor({ state: 'visible', timeout: 2000 });
+            await page.locator('input[type="password"]:visible').first().waitFor({ state: 'visible', timeout: 5000 });
         }
         catch {
             await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });

package/dist/tools/auth/explore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/explore.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAiNzE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAgL1B"}
+{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../../src/tools/auth/explore.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AA2PzE,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,SAAQ,EACjB,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAiM1B"}

package/dist/tools/auth/explore.js

@@ -185,6 +185,43 @@ async function buildFormPaths(page) {
         },
     ];
 }
+async function probeUserLocalProviderClick(page, providerLabel, loginUrl, timeoutMs) {
+    const originBefore = new URL(page.url()).origin;
+    let clicked = false;
+    try {
+        await page.getByRole('button', { name: providerLabel, exact: true }).first().click({ timeout: 3000 });
+        clicked = true;
+    }
+    catch {
+        try {
+            const escaped = providerLabel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            await page
+                .locator('button, [role="button"]')
+                .filter({ hasText: new RegExp(`^\\s*${escaped}\\s*$`, 'i') })
+                .first()
+                .click({ timeout: 3000 });
+            clicked = true;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    if (!clicked)
+        return [];
+    try {
+        await page.waitForLoadState('domcontentloaded', { timeout: 5000 });
+    }
+    catch { /* best-effort */ }
+    await waitNetworkIdleBestEffort(page);
+    if (new URL(page.url()).origin !== originBefore) {
+        await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+        return [];
+    }
+    const formPaths = await buildFormPaths(page);
+    await page.goto(loginUrl, { timeout: timeoutMs, waitUntil: 'domcontentloaded' });
+    await waitNetworkIdleBestEffort(page);
+    return formPaths;
+}
 export async function exploreAuth(url, timeoutMs = 20000, progress) {
     const browser = await launchBrowser();
     try {
@@ -246,6 +283,21 @@ export async function exploreAuth(url, timeoutMs = 20000, progress) {
                     continue;
                 }
                 consumed.add(id);
+                if (p.source === 'user-local') {
+                    const probed = await probeUserLocalProviderClick(page, p.label, finalUrl, timeoutMs);
+                    if (probed.length > 0) {
+                        for (const fp of probed) {
+                            authPaths.push({
+                                ...fp,
+                                id: p.id,
+                                label: p.label,
+                                source: 'user-local',
+                            });
+                            progress?.info(`explore_auth path id=${p.id} type=${fp.type} automatable=${fp.automatable} (user-local probe)`);
+                        }
+                        continue;
+                    }
+                }
                 authPaths.push({
                     id,
                     label: p.label,

package/dist/tools/scoring/automation-maturity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,6CAA6C,CAAC;AAiDrD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CAuLhF"}
+{"version":3,"file":"automation-maturity.d.ts","sourceRoot":"","sources":["../../../src/tools/scoring/automation-maturity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,6CAA6C,CAAC;AAiDrD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CAmMhF"}

package/dist/tools/scoring/automation-maturity.js

@@ -102,10 +102,13 @@ export function computeAutomationMaturity(repo) {
     let hygieneScore = 0;
     let hygieneApplicability = 'applicable';
     let hygieneReason;
+    let hygieneGuidance;
     const hygieneEvidence = [];
     if (interactiveTsxScanned === 0) {
         hygieneApplicability = 'unknown';
         hygieneReason = 'No interactive TSX files scanned — cannot compute a missing-id ratio honestly.';
+        hygieneGuidance =
+            'Qulib could not collect enough signal to score this dimension. Run against a repo with more test files or a larger page scan to improve signal.';
         hygieneEvidence.push(hygieneReason);
     }
     else {
@@ -123,6 +126,7 @@ export function computeAutomationMaturity(repo) {
             : [],
         applicability: hygieneApplicability,
         ...(hygieneReason && { reason: hygieneReason }),
+        ...(hygieneGuidance && { guidance: hygieneGuidance }),
     };
     const ci = hasCiAtRoot(repo.repoPath);
     const ciDim = {
@@ -141,10 +145,13 @@ export function computeAutomationMaturity(repo) {
     let authScore = 0;
     let authApplicability = 'applicable';
     let authReason;
+    let authGuidance;
     const authEvidence = [];
     if (!repoHasAnyAuthSignal) {
         authApplicability = 'not_applicable';
         authReason = 'No auth routes, auth-named test files, or auth path coverage detected — repo appears auth-free.';
+        authGuidance =
+            'No auth signal detected in this app. If authentication exists, run qulib with a storage-state file to enable auth-test-coverage scoring.';
         authEvidence.push(authReason);
     }
     else {
@@ -163,6 +170,7 @@ export function computeAutomationMaturity(repo) {
             : [],
         applicability: authApplicability,
         ...(authReason && { reason: authReason }),
+        ...(authGuidance && { guidance: authGuidance }),
     };
     const cypressE2e = repo.testFiles.filter((t) => t.type === 'cypress-e2e').length;
     const cypressComp = repo.testFiles.filter((t) => t.type === 'cypress-component').length;
@@ -170,10 +178,13 @@ export function computeAutomationMaturity(repo) {
     let compRatioScore = 0;
     let compApplicability = 'applicable';
     let compReason;
+    let compGuidance;
     const compEvidence = [];
     if (cypressTotal === 0) {
         compApplicability = 'not_applicable';
         compReason = 'No Cypress (e2e or component) tests detected — component-test-ratio does not apply.';
+        compGuidance =
+            'No Cypress component test setup detected. Add cypress/component/ tests and a component config to enable this dimension.';
         compEvidence.push(compReason);
     }
     else {
@@ -190,6 +201,7 @@ export function computeAutomationMaturity(repo) {
             : [],
         applicability: compApplicability,
         ...(compReason && { reason: compReason }),
+        ...(compGuidance && { guidance: compGuidance }),
     };
     const dimensions = [breadthDim, frameworkDim, hygieneDim, ciDim, authDim, compDim];
     // Overall score normalizes over applicable dimensions only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qulib/core",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Qulib — analyze deployed web apps for honest quality gaps (CLI + programmatic API)",
   "license": "MIT",
   "author": "Tapesh Nagarwal",
@@ -48,7 +48,7 @@
     "analyze": "tsx src/cli/index.ts analyze",
     "clean": "tsx src/cli/index.ts clean",
     "build": "tsc",
-    "test": "node --import tsx/esm --test src/llm/__tests__/cost-intelligence.test.ts src/tools/scoring/__tests__/gaps.test.ts src/tools/auth/__tests__/gaps.test.ts src/tools/auth/__tests__/detect.test.ts src/tools/scoring/__tests__/automation-maturity.test.ts src/harness/__tests__/state-manager.test.ts src/telemetry/__tests__/redact-url.test.ts src/cli/__tests__/auth-login.test.ts src/cli/__tests__/cli-version.test.ts src/__tests__/analyze.storage-state-invalid.test.ts",
+    "test": "node --import tsx/esm --test src/llm/__tests__/cost-intelligence.test.ts src/tools/scoring/__tests__/gaps.test.ts src/tools/auth/__tests__/gaps.test.ts src/tools/auth/__tests__/detect.test.ts src/tools/scoring/__tests__/automation-maturity.test.ts src/harness/__tests__/state-manager.test.ts src/telemetry/__tests__/redact-url.test.ts src/cli/__tests__/auth-login.test.ts src/cli/__tests__/cli-version.test.ts src/__tests__/analyze.storage-state-invalid.test.ts src/__tests__/analyze.fixtures.test.ts",
     "test:integration": "node --import tsx/esm --test src/__tests__/analyze.integration.test.ts",
     "smoke": "tsx src/cli/index.ts analyze --url https://example.com --ephemeral",
     "cost-doctor": "tsx src/cli/index.ts cost doctor"