codemini-cli 0.4.5 → 0.4.7

package/deployment.md

@@ -13,13 +13,13 @@ npm pack
 Expected output:
 
 ```text
-codemini-cli-0.4.5.tgz
+codemini-cli-0.4.7.tgz
 ```
 
 If you want to verify the package contents:
 
 ```bash
-tar -tf codemini-cli-0.4.5.tgz
+tar -tf codemini-cli-0.4.7.tgz
 ```
 
 ## 2. Copy To The Target Machine
@@ -34,7 +34,7 @@ Copy the generated `.tgz` file to the Win10 machine by one of these methods:
 Recommended target path:
 
 ```powershell
-C:\temp\codemini-cli-0.4.5.tgz
+C:\temp\codemini-cli-0.4.7.tgz
 ```
 
 ## 3. Environment Requirements
@@ -58,7 +58,7 @@ npm -v
 Global install:
 
 ```powershell
-npm install -g C:\temp\codemini-cli-0.4.5.tgz
+npm install -g C:\temp\codemini-cli-0.4.7.tgz
 ```
 
 If global install is blocked by company policy, install in a working directory instead:
@@ -66,7 +66,7 @@ If global install is blocked by company policy, install in a working directory i
 ```powershell
 mkdir C:\temp\coder-test
 cd C:\temp\coder-test
-npm install C:\temp\codemini-cli-0.4.5.tgz
+npm install C:\temp\codemini-cli-0.4.7.tgz
 ```
 
 ## 5. Confirm Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/skills/project-requirements/SKILL.md

@@ -32,16 +32,40 @@ docs/requirements/{{date}}-project-requirements.md
 
 The HTML should be self-contained: inline CSS, inline JavaScript, no build step, no required external assets.
 
+Use a clean, modern documentation style inspired by Notion and Linear unless the user asks otherwise:
+
+- White background, warm neutral palette (#37352f text, #e9e9e7 borders), blue accents (#2383e2).
+- Favor generous whitespace, clean typography, and subtle hover transitions over dense layouts.
+- Cards should have rounded corners, minimal borders, and subtle shadow on hover.
+- Tables should have uppercase header labels, no row background by default (only on hover).
+- Use pill-shaped badges for evidence and risk labels — colored background + matching text, no emoji.
+- Diagrams should look like polished internal architecture or business process documentation.
+- Avoid playful palettes, strong gradients, decorative blobs, and visually loud illustrations.
+
+Evidence badge class names — use `.tag` or `.badge` with these variants:
+
+| Variant | Use for | Visual |
+|---|---|---|
+| `.tag.extracted` / `.badge.extracted` | Behavior directly supported by source code | Green text on green background |
+| `.tag.inferred` / `.badge.inferred` | Reasonable inference from code relationships | Orange text on orange background |
+| `.tag.unknown` / `.badge.unknown` | Needs user confirmation | Gray text on gray background |
+| `.tag.warn` / `.badge.warn` | Medium risk or warning | Orange text on orange background |
+| `.tag.danger` / `.badge.danger` | Critical/high risk | Red text on red background |
+| `.tag.ok` / `.badge.ok` | Low risk or passed check | Green text on green background |
+
+Risk level indicators in tables must use the badge variants above, never emoji. For example: `<span class="badge danger">CRITICAL</span>` not `🔴 CRITICAL`.
+
+Wrap each requirement card in `<details class="card">` with a `<summary>` containing the API name and a one-line description. This makes all cards collapsible by default.
+
 When the target HTML file already exists and contains `REQUIREMENTS_*` marker sections, treat it as the canonical report shell. Edit those marker sections in place instead of replacing the whole file. Preserve the existing CSS, JavaScript, navigation, metadata, and surrounding structure unless the user explicitly asks to redesign the shell.
 
-Diagrams must be visible when the HTML is opened directly from disk:
+Diagrams must be visible and polished when the HTML is opened directly from disk:
 
-- Prefer inline SVG for architecture maps, dependency graphs, sequence summaries, and state diagrams.
-- Use semantic SVG groups, `<title>`/`<desc>`, readable labels, arrow markers, and stable element ids so sections can link to diagram nodes.
-- For simple hierarchy diagrams, CSS grid/flex boxes with connector lines are also acceptable.
-- Do not rely on Mermaid rendering as the only visible diagram. Mermaid source may be included in a collapsible `<details>` block as an editable source-of-truth companion.
-- Use Mermaid CDN rendering only as optional progressive enhancement when the user accepts network access. The static inline SVG or CSS diagram must remain the fallback and primary offline view.
-- Avoid showing only raw Mermaid code blocks in the final HTML unless the user explicitly asks for source-only diagrams.
+- Prefer custom inline SVG, CSS grid/flex diagrams, timeline layouts, swimlanes, and styled cards for architecture maps, dependency graphs, flow summaries, and state/lifecycle diagrams.
+- Use semantic SVG groups, `<title>`/`<desc>`, readable labels, arrow markers, stable element ids, and source evidence links where useful.
+- Keep diagrams evidence-based and readable. Prefer fewer correct nodes over a dense speculative map.
+- Do not use Mermaid as the rendered diagram format unless the user explicitly asks for Mermaid source.
+- Avoid showing raw diagram source blocks in the final HTML unless the user explicitly asks for source-only diagrams.
 
 For medium or large projects, do not generate the entire HTML document in one model response or one huge `write` call. Create the report incrementally:
 
@@ -69,10 +93,12 @@ This chunked approach is required for HTML reports because inline CSS, JavaScrip
    - Tool calls, MCP handlers, RPC methods, queue jobs, scheduled tasks, or exported SDK functions.
    - UI flows only after the backend/interface layer is mapped, unless the project is frontend-only.
 4. Connect each API/interface to requirements:
+   - Business capability supported by the interface.
    - User goal and actor.
    - Trigger and entry point.
    - Request/input shape.
    - Response/output shape.
+   - Business rules and decision points.
    - Validation and permission rules.
    - Data read/write behavior.
    - Internal modules called.
@@ -80,12 +106,13 @@ This chunked approach is required for HTML reports because inline CSS, JavaScrip
    - Error cases and retry/rollback behavior.
    - Observability, audit, and security notes.
    - Acceptance criteria.
+   - Open questions that block final confirmation.
 5. Generate diagrams:
    - Product flowchart for the main user journey.
    - API dependency graph linking endpoints/commands to modules, data stores, and external services.
    - Sequence diagram for at least one high-value flow.
    - State or lifecycle diagram when the domain has clear states.
-   - Render each diagram as static inline SVG or CSS boxes in the HTML, with optional Mermaid source hidden in a collapsible details block.
+   - Render each diagram as polished inline HTML/CSS or SVG that is visible offline without external JavaScript.
 6. Write the report and preserve traceability:
    - Link sections with stable anchors.
    - Include code file paths for evidence.
@@ -158,30 +185,30 @@ Open questions:
 
 ## Diagram Patterns
 
-Use static diagrams when diagrams help compress complexity. In HTML output, render the visible diagram as inline SVG or CSS boxes. Include Mermaid only as optional source text when it helps future editing.
+Use custom HTML/CSS/SVG diagrams when diagrams help compress complexity. The visual output should look intentional, readable, and report-quality, not like raw generated graph syntax.
 
 Inline SVG architecture map:
 
 ```html
-<figure class="diagram" id="system-architecture">
+<figure class="diagram-card" id="system-architecture">
   <figcaption>System architecture</figcaption>
-  <svg viewBox="0 0 960 520" role="img" aria-labelledby="arch-title arch-desc">
+  <svg viewBox="0 0 960 380" role="img" aria-labelledby="arch-title arch-desc">
     <title id="arch-title">System architecture</title>
-    <desc id="arch-desc">CLI commands call runtime services, which use tools and data stores.</desc>
+    <desc id="arch-desc">CLI entry points call the runtime, which coordinates tools and persisted session state.</desc>
     <defs>
       <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
         <path d="M0,0 L0,6 L9,3 z"></path>
       </marker>
     </defs>
-    <g id="cli-layer">
-      <rect x="40" y="40" width="220" height="90" rx="8"></rect>
-      <text x="60" y="90">CLI Entry</text>
+    <g class="node">
+      <rect x="48" y="72" width="190" height="86" rx="10"></rect>
+      <text x="72" y="122">CLI Entry</text>
     </g>
-    <g id="runtime-layer">
-      <rect x="370" y="40" width="240" height="90" rx="8"></rect>
-      <text x="390" y="90">Runtime</text>
+    <g class="node">
+      <rect x="386" y="72" width="210" height="86" rx="10"></rect>
+      <text x="410" y="122">Runtime</text>
     </g>
-    <line x1="260" y1="85" x2="370" y2="85" marker-end="url(#arrow)"></line>
+    <line x1="238" y1="115" x2="386" y2="115" marker-end="url(#arrow)"></line>
   </svg>
 </figure>
 ```
@@ -189,50 +216,52 @@ Inline SVG architecture map:
 CSS box architecture map:
 
 ```html
-<section class="arch-map" aria-label="System architecture">
-  <a class="arch-node" href="#api-chat">Chat command</a>
-  <span class="arch-edge" aria-hidden="true">-></span>
-  <a class="arch-node" href="#runtime-agent-loop">Agent loop</a>
-  <span class="arch-edge" aria-hidden="true">-></span>
-  <a class="arch-node" href="#tools-write">Tools</a>
+<section class="dependency-map" aria-label="System architecture">
+  <a class="dep-node" href="#api-chat">Chat command</a>
+  <span class="dep-edge">→</span>
+  <a class="dep-node" href="#runtime-agent-loop">Agent loop</a>
+  <span class="dep-edge">→</span>
+  <a class="dep-node" href="#tools-write">Tools</a>
 </section>
 ```
 
-Optional Mermaid companion:
-
 Product flow:
 
-```mermaid
-flowchart TD
-  A[User starts task] --> B[System validates input]
-  B --> C[System performs core action]
-  C --> D[User receives result]
+```html
+<ol class="flow-steps" aria-label="Product flow">
+  <li><strong>User starts task</strong><span>Input is collected from CLI or UI.</span></li>
+  <li><strong>System validates input</strong><span>Policy, mode, and project context are checked.</span></li>
+  <li><strong>System performs core action</strong><span>Runtime coordinates model calls and tools.</span></li>
+  <li><strong>User receives result</strong><span>Final answer, artifacts, and evidence are returned.</span></li>
+</ol>
 ```
 
 API dependency map:
 
-```mermaid
-graph LR
-  API[API or command] --> Handler[Handler]
-  Handler --> Service[Service]
-  Service --> Store[(Data store)]
-  Service --> External[External service]
+```html
+<section class="dependency-map" aria-label="API dependency map">
+  <a class="dep-node" href="#api-command">API or command</a>
+  <span class="dep-edge">→</span>
+  <a class="dep-node" href="#handler">Handler</a>
+  <span class="dep-edge">→</span>
+  <a class="dep-node" href="#service">Service</a>
+  <span class="dep-edge">→</span>
+  <a class="dep-node" href="#store">Data store</a>
+</section>
 ```
 
 Sequence flow:
 
-```mermaid
-sequenceDiagram
-  participant User
-  participant API
-  participant Service
-  participant Store
-  User->>API: Request
-  API->>Service: Validate and execute
-  Service->>Store: Read/write data
-  Store-->>Service: Result
-  Service-->>API: Domain result
-  API-->>User: Response
+```html
+<table class="sequence-table">
+  <thead><tr><th>Step</th><th>Sender</th><th>Receiver</th><th>Message</th></tr></thead>
+  <tbody>
+    <tr><td>1</td><td>User</td><td>API</td><td>Request</td></tr>
+    <tr><td>2</td><td>API</td><td>Service</td><td>Validate and execute</td></tr>
+    <tr><td>3</td><td>Service</td><td>Store</td><td>Read/write data</td></tr>
+    <tr><td>4</td><td>API</td><td>User</td><td>Response</td></tr>
+  </tbody>
+</table>
 ```
 
 ## Quality Bar
@@ -245,3 +274,18 @@ The report is complete when:
 - Inferred requirements are labeled instead of stated as facts.
 - Open questions are grouped so the user can resolve them later.
 - The HTML can be opened directly from disk in a browser.
+
+## Content Guidelines
+
+Avoid duplication between sections:
+
+- The Executive Summary risk list should contain only the **top 2-3 most critical risks** with one-sentence descriptions. The full risk matrix belongs in the Security section only.
+- Key capabilities in the summary should be a concise table (name + one-liner + evidence). Detailed descriptions belong in the per-API requirement cards.
+- Non-functional findings should appear only in the Non-functional section, not duplicated in the summary.
+
+Open questions should be **actionable and specific**:
+
+- Do NOT list questions that can be answered by reading the source code (e.g. "What is the test coverage?", "Is there CI/CD?"). Instead, investigate and report the answer directly.
+- Do NOT list questions about whether a feature exists — check the code first and report what you find.
+- Only list questions that require **human decision-making**, **business context**, or **stakeholder input** that cannot be derived from the codebase.
+- Each open question should clearly state what decision or confirmation is needed and why it matters.

package/src/commands/chat.js

@@ -42,7 +42,7 @@ function parseChatArgs(args) {
   return parsed;
 }
 
-export async function submitAndPrint(runtime, line, { output: out = process.stdout } = {}) {
+export async function submitAndPrint(runtime, line, { output: out = process.stdout, showSystemTools = false } = {}) {
   let streamed = false;
   let atLineStart = true;
   const write = (text) => {
@@ -84,6 +84,9 @@ export async function submitAndPrint(runtime, line, { output: out = process.stdo
       writeActivity(event, 'tool:error');
       return;
     }
+    if (!showSystemTools && String(event?.type || '').startsWith('system_tool:')) {
+      return;
+    }
     if (event?.type === 'system_tool:start') {
       streamed = true;
       writeActivity(event, 'system:start');

package/src/core/agent-loop.js

@@ -779,7 +779,16 @@ export async function runAgentLoop({
       if (onEvent) onEvent({ type: 'tool:start', name: displayName, id: call.id, arguments: effectiveArgs });
       const handler = toolHandlers[toolName];
       if (!handler) {
-        throw new Error(`Unknown tool: ${call.name}`);
+        const available = Object.keys(toolHandlers).join(', ');
+        const msg = `Unknown tool: "${toolName}". Available tools: ${available || '(none)'}`;
+        if (onEvent) {
+          onEvent({ type: 'tool:error', name: displayName, id: call.id, arguments: effectiveArgs, durationMs: 0, summary: trimInline(msg, 200) });
+        }
+        return {
+          callId: call.id,
+          content: JSON.stringify({ error: msg }),
+          error: true
+        };
       }
 
       const blockedReason = blockedExplorationReason(toolName, effectiveArgs, analysisGuard);

package/src/core/chat-runtime.js

@@ -321,6 +321,19 @@ const SUB_AGENT_CONTEXT_MAX_MESSAGES = 4;
 const SUB_AGENT_CONTEXT_MAX_CHARS = 1200;
 const SUB_AGENT_EVIDENCE_MAX_ITEMS = 3;
 const SUB_AGENT_HANDOFF_MAX_ITEMS = 6;
+const PROJECT_REQUIREMENTS_SECTION_MARKERS = [
+  { key: 'summary', marker: 'REQUIREMENTS_SUMMARY', labels: ['1', 'summary', 'overview', 'project overview', 'executive summary', '项目概述', '项目总览', '概述'] },
+  { key: 'architecture', marker: 'REQUIREMENTS_ARCHITECTURE', labels: ['2', 'architecture', 'system architecture', 'system map', '架构', '系统架构图', '系统架构', '架构图'] },
+  { key: 'interfaces', marker: 'REQUIREMENTS_INTERFACE_INVENTORY', labels: ['3', 'interface inventory', 'interfaces', 'api inventory', '接口清单', '接口', 'api清单'] },
+  { key: 'requirements', marker: 'REQUIREMENTS_API_CARDS', labels: ['4', 'requirement cards', 'api cards', 'interface requirements', '接口需求卡片', '需求卡片'] },
+  { key: 'flows', marker: 'REQUIREMENTS_FLOWS', labels: ['5', 'flows', 'user flows', 'core flows', '核心用户流程', '用户流程', '流程'] },
+  { key: 'domain', marker: 'REQUIREMENTS_DOMAIN_MODEL', labels: ['6', 'domain model', 'data ownership', 'domain', '领域模型', '数据归属', '领域模型与数据归属'] },
+  { key: 'security', marker: 'REQUIREMENTS_SECURITY', labels: ['7', 'security', 'permissions', 'compliance', '权限', '安全', '合规', '权限、安全与合规'] },
+  { key: 'errors', marker: 'REQUIREMENTS_ERROR_HANDLING', labels: ['8', 'errors', 'edge cases', 'error handling', '异常处理', '边界情况', '异常处理与边界情况'] },
+  { key: 'nonfunctional', marker: 'REQUIREMENTS_NONFUNCTIONAL', labels: ['9', 'non-functional', 'nonfunctional', 'nfr', '非功能性需求', '非功能'] },
+  { key: 'questions', marker: 'REQUIREMENTS_OPEN_QUESTIONS', labels: ['10', 'open questions', 'unknowns', '待确认问题', '待确认', '问题'] },
+  { key: 'evidence', marker: 'REQUIREMENTS_EVIDENCE_INDEX', labels: ['11', 'evidence', 'source evidence', 'source evidence index', '源码证据索引', '证据索引', '源码证据'] }
+];
 const PLAN_MEMORY_MARKERS = {
   findings: ['<!-- plan-findings-start -->', '<!-- plan-findings-end -->'],
   progress: ['<!-- plan-progress-start -->', '<!-- plan-progress-end -->']
@@ -2993,7 +3006,41 @@ function renderAutoPlanMarkdown({
   return lines.join('\n');
 }
 
+function parseProjectRequirementsOptions(args = []) {
+  const raw = args.join(' ').trim();
+  const normalized = raw.toLowerCase();
+  const hasIgnoreIntent = /(忽略|跳过|不生成|不要|无需|排除|exclude|skip|omit|without|no\s+)/i.test(raw);
+  if (!hasIgnoreIntent) return { raw, ignoredSections: [] };
+
+  const ignored = [];
+  for (const section of PROJECT_REQUIREMENTS_SECTION_MARKERS) {
+    const matched = section.labels.some((label) => {
+      const value = String(label).toLowerCase();
+      if (/^\d+$/.test(value)) {
+        return new RegExp(`(^|[^0-9])${value}([^0-9]|$)`).test(normalized);
+      }
+      return normalized.includes(value);
+    });
+    if (matched) ignored.push(section);
+  }
+  return { raw, ignoredSections: ignored };
+}
+
+function renderProjectRequirementsSectionContract(ignoredSections = []) {
+  const ignored = new Set(ignoredSections.map((section) => section.marker));
+  const required = PROJECT_REQUIREMENTS_SECTION_MARKERS
+    .filter((section) => !ignored.has(section.marker))
+    .map((section) => section.marker);
+  const lines = [`Required marker sections: ${required.join(', ')}.`];
+  if (ignoredSections.length > 0) {
+    lines.push(`User-requested omitted sections: ${ignoredSections.map((section) => `${section.key} (${section.marker})`).join(', ')}.`);
+    lines.push('For omitted sections, leave the shell section visibly marked as omitted and do not spend analysis or writing budget filling it.');
+  }
+  return lines.join('\n');
+}
+
 function buildProjectRequirementsSteps(renderedSkillPrompt, args = []) {
+  const options = parseProjectRequirementsOptions(args);
   const userArgs = args.join(' ').trim();
   const requestedFocus = userArgs ? `User request/focus: ${userArgs}` : 'User request/focus: full workspace requirements report.';
   const reportDate = formatLocalDate();
@@ -3005,50 +3052,86 @@ function buildProjectRequirementsSteps(renderedSkillPrompt, args = []) {
     `Optional companion Markdown path: ${companionPath}`,
     'A pre-created HTML shell already exists at the primary report path.',
     'Fill or replace only the named marker sections in that shell instead of rewriting the whole document.',
-    'Required marker sections: REQUIREMENTS_SUMMARY, REQUIREMENTS_ARCHITECTURE, REQUIREMENTS_INTERFACE_INVENTORY, REQUIREMENTS_API_CARDS, REQUIREMENTS_FLOWS, REQUIREMENTS_SECURITY, REQUIREMENTS_NONFUNCTIONAL, REQUIREMENTS_OPEN_QUESTIONS, REQUIREMENTS_EVIDENCE_INDEX.',
+    renderProjectRequirementsSectionContract(options.ignoredSections),
+    'For diagrams, write polished inline HTML/CSS or SVG directly in the report. Do not use Mermaid unless the user explicitly asks for Mermaid source.',
+    'Use a light blue, white, and cool gray banking/financial visual style: conservative, dense, readable, and enterprise-grade.',
+    'Prioritize API/interface-level business requirements. Every major interface should map to business capability, actor, trigger, inputs, outputs, rules, permissions, data reads/writes, errors, acceptance criteria, and evidence.',
     'Use EXTRACTED, INFERRED, and UNKNOWN labels. Preserve source evidence paths.',
     'Do not invent dates; use the report paths above.'
   ].join('\n');
 
   return [
     {
-      title: 'Map project interfaces and evidence',
+      title: '🧭 Map entry points and evidence sources',
       role: 'planner',
       task: [
-        'Map project interfaces and evidence before any report writing.',
+        'Map project entry points and evidence sources before any report writing.',
         reportContract,
         'Inspect top-level docs, package manifests, route/command entry points, tests, and obvious interface files.',
-        'Produce a concise interface inventory grouped by CLI commands, HTTP/API/RPC surfaces, tools, storage/config, UI flows, and operations.',
+        'Produce a concise evidence map grouped by docs, routes/commands, handlers, schemas, tests, configuration, storage, and operations.',
         'Include evidence paths and open questions. Do not write the final report.'
       ].join('\n')
     },
     {
-      title: 'Analyze runtime, tools, and providers',
+      title: '📚 Build API and interface inventory',
+      role: 'planner',
+      task: [
+        'Build the canonical API/interface inventory using the evidence map.',
+        reportContract,
+        'Enumerate every major HTTP endpoint, CLI command, tool call, MCP/RPC handler, queue/scheduled job, exported SDK function, and user-facing workflow entry point.',
+        'For each item include type, route/command/function, owner module, evidence path, likely actor, and whether it is EXTRACTED, INFERRED, or UNKNOWN.',
+        'Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: '🧩 Decompose business requirements per API',
+      role: 'advisor',
+      task: [
+        'Decompose business requirements for each major API/interface from the inventory.',
+        reportContract,
+        'For each interface capture business capability, actor, user goal, trigger, inputs, outputs, preconditions, main flow, alternate flows, business rules, acceptance criteria, and open questions.',
+        'Keep findings API-centered rather than module-centered. Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: '🔐 Analyze validation, permissions, and compliance',
+      role: 'advisor',
+      task: [
+        'Analyze validation, authorization, security, audit, and compliance implications per API/interface.',
+        reportContract,
+        'For each relevant interface identify validation rules, permission checks, sensitive data, audit/traceability needs, policy constraints, retry/rollback behavior, and UNKNOWN compliance gaps.',
+        'Return requirement-ready findings with evidence paths. Do not write the final report.'
+      ].join('\n')
+    },
+    {
+      title: '💾 Map data ownership and state changes',
       role: 'advisor',
       task: [
-        'Analyze the core execution layer and tool/provider surfaces using the prior planner inventory.',
+        'Map data ownership, storage paths, state transitions, and side effects per API/interface.',
         reportContract,
-        'Focus on runtime flow, agent loop, built-in/deferred tools, provider streaming/tool-call behavior, sessions, memory, and plan state.',
-        'Return requirement-ready findings with evidence paths, inferred requirements, edge cases, and unknowns. Do not write the final report.'
+        'Identify data reads, data writes, config/session/memory/file/database ownership, lifecycle states, cache/index behavior, external dependencies, and operational side effects.',
+        'Return requirement-ready findings with evidence paths. Do not write the final report.'
       ].join('\n')
     },
     {
-      title: 'Analyze product flows, storage, security, and operations',
+      title: '🔄 Connect user flows to API dependencies',
       role: 'advisor',
       task: [
-        'Analyze user-facing workflows and non-functional requirements using the accumulated plan context.',
+        'Connect user-facing flows to the API/interface inventory and implementation dependencies.',
         reportContract,
-        'Cover core product journeys, persistence paths, configuration, security/policy behavior, deployment/operations notes, error handling, and acceptance criteria.',
-        'Return requirement-ready findings with evidence paths, inferred requirements, edge cases, and unknowns. Do not write the final report.'
+        'Create flow-ready findings for core journeys, API dependency maps, sequence summaries, error paths, and cross-interface handoffs.',
+        'Favor clear business process decomposition over broad architecture prose. Do not write the final report.'
       ].join('\n')
     },
     {
-      title: 'Write requirements HTML report',
+      title: '🎨 Write banking-style requirements HTML report',
       role: 'coder',
       task: [
         'Create the final project requirements report from the accumulated plan context.',
         reportContract,
         'Follow the project-requirements skill instructions below exactly, including chunked HTML writing for medium/large reports.',
+        'Use the blue/white/gray banking-style shell and produce polished inline HTML/CSS/SVG diagrams. Keep the report professional, light, and conservative.',
+        'Organize the main requirements section primarily by API/interface business requirement cards.',
         'The final HTML must be self-contained and directly openable from disk.',
         'Write the primary report to the exact primary report path above. Create the companion Markdown only if useful.',
         'Skill instructions:',
@@ -3056,22 +3139,23 @@ function buildProjectRequirementsSteps(renderedSkillPrompt, args = []) {
       ].join('\n\n')
     },
     {
-      title: 'Review report coverage and traceability',
+      title: '🔎 Review API coverage and traceability',
       role: 'reviewer',
       task: [
         'Review the generated requirements report against the project-requirements contract and accumulated evidence.',
         reportContract,
-        'Check that major interfaces are represented, evidence paths are present, inferred/unknown content is labeled, diagrams are visible without Mermaid as the only renderer, and the report path matches the required local date.',
+        'Check that major APIs/interfaces are represented, business requirements are decomposed per API, evidence paths are present, inferred/unknown content is labeled, diagrams are visible as inline HTML/CSS/SVG without external rendering libraries, and the report path matches the required local date.',
+        'Check that the visual style is light blue/white/gray and suitable for banking/financial review.',
         'Report concrete gaps and risks only. Do not rewrite the whole report.'
       ].join('\n')
     },
     {
-      title: 'Summarize final requirements report',
+      title: '🧾 Summarize final report and unresolved questions',
       role: 'summarizer',
       task: [
         'Synthesize the project requirements pipeline results into a concise final status for the user.',
         reportContract,
-        'Mention the generated report path, what was covered, what was not verified, and the best next action.',
+        'Mention the generated report path, API/interface coverage, strongest business requirement findings, unresolved questions, what was not verified, and the best next action.',
         'Do not re-analyze the codebase unless the accumulated evidence is clearly insufficient.'
       ].join('\n')
     }
@@ -3138,7 +3222,9 @@ async function createProjectRequirementsShell({
     'interfaces',
     'requirements',
     'flows',
+    'domain',
     'security',
+    'errors',
     'nonfunctional',
     'questions',
     'evidence'
@@ -3255,8 +3341,23 @@ async function runProjectRequirementsPipeline({
         name: custom.name,
         summary: error instanceof Error ? error.message : String(error)
       });
+      onAgentEvent({ type: 'skill:end', name: custom.name });
     }
-    throw error;
+    if (manifestPath) {
+      await updateProjectRequirementsManifest(manifestPath, {
+        status: 'failed',
+        failedCount: steps.length,
+        error: error instanceof Error ? error.message : String(error)
+      }).catch(() => {});
+    }
+    return {
+      type: 'assistant',
+      text: `Project requirements pipeline failed: ${error instanceof Error ? error.message : String(error)}`,
+      planFile,
+      reportPath,
+      manifestPath,
+      aborted: true
+    };
   }
   if (onAgentEvent) {
     onAgentEvent({
@@ -4929,8 +5030,12 @@ export async function createChatRuntime({
             name: custom.name,
             summary: error instanceof Error ? error.message : String(error)
           });
+          onAgentEvent({ type: 'skill:end', name: custom.name });
         }
-        throw error;
+        return {
+          type: 'system',
+          text: `Skill "${custom.name}" failed: ${error instanceof Error ? error.message : String(error)}`
+        };
       }
       if (custom.metadata.type === 'skill' && onAgentEvent) {
         onAgentEvent({ type: 'skill:end', name: custom.name });

package/src/core/fff-adapter.js

@@ -111,7 +111,7 @@ class FffMcpClient {
       capabilities: {},
       clientInfo: {
         name: 'codemini-cli',
-        version: '0.4.5'
+        version: '0.4.7'
       }
     });
     this.sendNotification('notifications/initialized', {});

package/templates/project-requirements/report-shell.html

@@ -6,80 +6,397 @@
   <title>{{title}}</title>
   <style>
     :root {
-      color-scheme: light dark;
-      --bg: #f7f8fb;
+      color-scheme: light;
+      --bg: #ffffff;
+      --bg-muted: #f7f7f5;
+      --bg-hover: #f0f0ee;
       --panel: #ffffff;
-      --text: #182033;
-      --muted: #657086;
-      --line: #d9deea;
-      --accent: #2563eb;
-      --ok: #147a4a;
-      --warn: #a16207;
-      --unknown: #7c3aed;
-    }
-    @media (prefers-color-scheme: dark) {
-      :root {
-        --bg: #111521;
-        --panel: #181d2b;
-        --text: #edf2ff;
-        --muted: #a6afc3;
-        --line: #30384f;
-        --accent: #7aa2ff;
-      }
+      --text: #37352f;
+      --text-secondary: #787774;
+      --line: #e9e9e7;
+      --line-strong: #dfdfde;
+      --accent: #2383e2;
+      --accent-hover: #1b6ec2;
+      --accent-bg: #e8f0fe;
+      --red: #eb5757;
+      --red-bg: #ffefef;
+      --orange: #e9730c;
+      --orange-bg: #fff4e5;
+      --green: #4dab6f;
+      --green-bg: #edf7f0;
+      --gray: #9b9a97;
+      --gray-bg: #f1f1f0;
+      --shadow-sm: 0 1px 2px rgba(0,0,0,0.04);
+      --shadow-md: 0 2px 8px rgba(0,0,0,0.06);
+      --radius: 6px;
+      --radius-lg: 10px;
+      --transition: 120ms ease;
     }
-    * { box-sizing: border-box; }
+    * { box-sizing: border-box; margin: 0; }
     body {
-      margin: 0;
       background: var(--bg);
       color: var(--text);
-      font: 15px/1.55 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      font: 14.5px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      -webkit-font-smoothing: antialiased;
+      -moz-osx-font-smoothing: grayscale;
     }
+    /* ── Header ── */
     header {
-      padding: 32px min(5vw, 56px) 22px;
+      padding: 48px min(6vw, 80px) 28px;
       border-bottom: 1px solid var(--line);
-      background: var(--panel);
+      background: var(--bg);
+    }
+    h1, h2, h3, h4 { line-height: 1.25; color: var(--text); }
+    h1 { margin: 0 0 8px; font-size: clamp(26px, 3.5vw, 38px); font-weight: 700; letter-spacing: -0.02em; }
+    h2 { margin: 40px 0 16px; font-size: 22px; font-weight: 600; letter-spacing: -0.01em; }
+    h3 { margin: 20px 0 8px; font-size: 16px; font-weight: 600; }
+    a { color: var(--accent); text-decoration: none; transition: color var(--transition); }
+    a:hover { color: var(--accent-hover); text-decoration: underline; }
+    .meta {
+      color: var(--text-secondary);
+      font-size: 13px;
+      display: flex;
+      gap: 16px;
+      flex-wrap: wrap;
+      margin-top: 4px;
+    }
+    .meta span::before { content: ""; display: inline-block; width: 3px; height: 3px; border-radius: 50%; background: var(--gray); vertical-align: middle; margin-right: 8px; }
+    .meta span:first-child::before { display: none; }
+    /* ── Layout ── */
+    .layout {
+      display: grid;
+      grid-template-columns: minmax(200px, 260px) minmax(0, 1fr);
+      gap: 0;
+      min-height: calc(100vh - 140px);
+    }
+    /* ── Sidebar Nav ── */
+    nav {
+      position: sticky;
+      top: 0;
+      align-self: start;
+      height: calc(100vh - 140px);
+      overflow-y: auto;
+      border-right: 1px solid var(--line);
+      padding: 20px 12px 20px 0;
+      scrollbar-width: thin;
+    }
+    nav a {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 6px 12px;
+      border-radius: var(--radius);
+      text-decoration: none;
+      color: var(--text-secondary);
+      font-size: 13.5px;
+      font-weight: 500;
+      transition: all var(--transition);
+      border-bottom: none;
+    }
+    nav a:hover {
+      background: var(--bg-hover);
+      color: var(--text);
+      text-decoration: none;
+    }
+    nav a.active {
+      background: var(--bg-hover);
+      color: var(--text);
+      font-weight: 600;
+    }
+    nav a .nav-dot {
+      width: 6px;
+      height: 6px;
+      border-radius: 50%;
+      background: var(--line-strong);
+      flex-shrink: 0;
+      transition: background var(--transition);
+    }
+    nav a:hover .nav-dot,
+    nav a.active .nav-dot { background: var(--accent); }
+    /* ── Main Content ── */
+    main {
+      max-width: 920px;
+      padding: 8px min(5vw, 80px) 80px;
+    }
+    section {
+      padding: 4px 0 24px;
+      border-bottom: 1px solid var(--line);
+    }
+    section:last-child { border-bottom: none; }
+    /* ── Controls ── */
+    .controls { margin: 8px 0 24px; }
+    .controls-bar {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      flex-wrap: wrap;
     }
-    h1, h2, h3 { line-height: 1.2; }
-    h1 { margin: 0 0 10px; font-size: clamp(28px, 4vw, 44px); }
-    h2 { margin: 36px 0 14px; font-size: 24px; }
-    h3 { margin: 24px 0 10px; font-size: 18px; }
-    a { color: var(--accent); }
-    .meta { color: var(--muted); display: flex; gap: 16px; flex-wrap: wrap; }
-    .layout { display: grid; grid-template-columns: minmax(180px, 260px) minmax(0, 1fr); gap: 28px; padding: 24px min(5vw, 56px) 56px; }
-    nav { position: sticky; top: 16px; align-self: start; }
-    nav a { display: block; padding: 8px 0; text-decoration: none; border-bottom: 1px solid color-mix(in srgb, var(--line), transparent 45%); }
-    main { max-width: 1180px; }
-    section { padding: 2px 0 18px; border-bottom: 1px solid var(--line); }
-    .controls { display: flex; gap: 10px; flex-wrap: wrap; margin: 12px 0 22px; }
     input[type="search"] {
-      width: min(520px, 100%);
-      padding: 10px 12px;
+      width: min(400px, 100%);
+      padding: 7px 12px 7px 32px;
       border: 1px solid var(--line);
-      border-radius: 8px;
-      background: var(--panel);
+      border-radius: var(--radius);
+      background: var(--bg) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' fill='none' stroke='%239b9a97' stroke-width='2'%3E%3Ccircle cx='6' cy='6' r='4.5'/%3E%3Cpath d='M10 10l3 3'/%3E%3C/svg%3E") 10px center no-repeat;
+      color: var(--text);
+      font-size: 13.5px;
+      transition: border-color var(--transition), box-shadow var(--transition);
+    }
+    input[type="search"]:focus {
+      outline: none;
+      border-color: var(--accent);
+      box-shadow: 0 0 0 3px var(--accent-bg);
+    }
+    input[type="search"]::placeholder { color: var(--gray); }
+    .controls-bar button {
+      padding: 6px 14px;
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      background: var(--bg);
+      color: var(--text-secondary);
+      cursor: pointer;
+      font-size: 12.5px;
+      font-weight: 500;
+      transition: all var(--transition);
+    }
+    .controls-bar button:hover {
+      background: var(--bg-hover);
       color: var(--text);
+      border-color: var(--line-strong);
     }
+    .no-results { color: var(--gray); padding: 32px 0; font-size: 14px; display: none; }
+    /* ── Cards ── */
     .card {
       border: 1px solid var(--line);
-      border-radius: 8px;
+      border-radius: var(--radius-lg);
       background: var(--panel);
+      padding: 20px 24px;
+      margin: 16px 0;
+      transition: box-shadow var(--transition);
+    }
+    .card:hover { box-shadow: var(--shadow-md); }
+    /* ── Details (collapsible API cards) ── */
+    details.card summary {
+      cursor: pointer;
+      font-size: 15px;
+      font-weight: 600;
+      padding: 2px 0;
+      list-style: none;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+    details.card summary::-webkit-details-marker { display: none; }
+    details.card summary::before {
+      content: "";
+      display: inline-block;
+      width: 0; height: 0;
+      border-left: 5px solid var(--text-secondary);
+      border-top: 4px solid transparent;
+      border-bottom: 4px solid transparent;
+      transition: transform var(--transition);
+      flex-shrink: 0;
+    }
+    details.card[open] summary::before { transform: rotate(90deg); }
+    details.card summary:hover { color: var(--accent); }
+    details.card[open] summary {
+      padding-bottom: 16px;
+      margin-bottom: 16px;
+      border-bottom: 1px solid var(--line);
+    }
+    /* ── Badges / Tags ── */
+    .tag, .badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      border-radius: 4px;
+      padding: 1px 7px;
+      font-size: 11.5px;
+      font-weight: 600;
+      letter-spacing: 0.02em;
+      line-height: 20px;
+      white-space: nowrap;
+    }
+    .tag.extracted, .badge.extracted { color: var(--green); background: var(--green-bg); }
+    .tag.inferred, .badge.inferred { color: var(--orange); background: var(--orange-bg); }
+    .tag.unknown, .badge.unknown { color: var(--gray); background: var(--gray-bg); }
+    .tag.warn, .badge.warn { color: var(--orange); background: var(--orange-bg); }
+    .tag.danger, .badge.danger { color: var(--red); background: var(--red-bg); }
+    .tag.ok, .badge.ok { color: var(--green); background: var(--green-bg); }
+    /* ── Tables ── */
+    .table-wrap { overflow-x: auto; margin: 12px 0; border-radius: var(--radius); }
+    table, .spec-table, .sequence-table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 12px 0;
+      font-size: 13.5px;
+    }
+    th, td {
+      text-align: left;
+      vertical-align: top;
+      padding: 8px 12px;
+      border-bottom: 1px solid var(--line);
+    }
+    th {
+      color: var(--text-secondary);
+      font-size: 12px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      background: transparent;
+    }
+    tr:last-child td { border-bottom: none; }
+    tr:hover td { background: var(--bg-muted); }
+    /* ── Code ── */
+    code, pre {
+      font-family: "SFMono-Regular", "Menlo", "Consolas", "PT Mono", monospace;
+    }
+    code {
+      background: var(--bg-muted);
+      padding: 2px 5px;
+      border-radius: 3px;
+      font-size: 13px;
+      color: #eb5757;
+    }
+    pre {
+      overflow: auto;
       padding: 16px;
+      border-radius: var(--radius);
+      background: #fafaf8;
+      border: 1px solid var(--line);
+      font-size: 13px;
+      line-height: 1.5;
+    }
+    /* ── Diagrams ── */
+    .diagram, .diagram-card {
+      overflow: auto;
+      border: 1px solid var(--line);
+      border-radius: var(--radius-lg);
+      background: var(--bg);
+      padding: 20px;
+      margin: 16px 0;
+    }
+    .diagram-card figcaption {
+      color: var(--text-secondary);
+      font-weight: 600;
+      font-size: 13px;
+      margin: 0 0 16px;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+    }
+    .diagram svg { max-width: 100%; height: auto; }
+    .diagram-card svg { width: 100%; height: auto; }
+    /* ── Flow Steps ── */
+    .flow-steps {
+      display: grid;
+      gap: 2px;
       margin: 12px 0;
+      padding: 0;
+      list-style: none;
+      counter-reset: step;
     }
-    .tag { display: inline-flex; align-items: center; border-radius: 999px; padding: 2px 8px; font-size: 12px; font-weight: 700; }
-    .tag.extracted { color: var(--ok); border: 1px solid color-mix(in srgb, var(--ok), transparent 45%); }
-    .tag.inferred { color: var(--warn); border: 1px solid color-mix(in srgb, var(--warn), transparent 45%); }
-    .tag.unknown { color: var(--unknown); border: 1px solid color-mix(in srgb, var(--unknown), transparent 45%); }
-    table { width: 100%; border-collapse: collapse; margin: 12px 0; }
-    th, td { text-align: left; vertical-align: top; padding: 9px 10px; border-bottom: 1px solid var(--line); }
-    th { color: var(--muted); font-size: 13px; }
-    code, pre { font-family: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace; }
-    pre { overflow: auto; padding: 14px; border-radius: 8px; background: color-mix(in srgb, var(--panel), var(--line) 18%); }
-    .diagram { overflow: auto; }
-    .placeholder { color: var(--muted); font-style: italic; }
+    .flow-steps li {
+      counter-increment: step;
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      background: var(--bg-muted);
+      padding: 14px 16px 14px 48px;
+      position: relative;
+      transition: background var(--transition);
+    }
+    .flow-steps li:hover { background: var(--bg-hover); }
+    .flow-steps li::before {
+      content: counter(step);
+      position: absolute;
+      left: 16px;
+      top: 14px;
+      width: 22px;
+      height: 22px;
+      border-radius: 50%;
+      background: var(--accent);
+      color: #fff;
+      font-size: 11px;
+      font-weight: 700;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .flow-steps span { display: block; color: var(--text-secondary); margin-top: 4px; font-size: 13px; }
+    /* ── Dependency Map ── */
+    .dependency-map {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      flex-wrap: wrap;
+      margin: 12px 0;
+    }
+    .dep-node {
+      border: 1px solid var(--line);
+      border-radius: var(--radius);
+      background: var(--bg-muted);
+      padding: 8px 14px;
+      text-decoration: none;
+      font-size: 13px;
+      font-weight: 500;
+      transition: all var(--transition);
+    }
+    .dep-node:hover {
+      background: var(--bg-hover);
+      border-color: var(--line-strong);
+      text-decoration: none;
+      color: var(--accent);
+    }
+    .dep-edge { color: var(--line-strong); font-weight: 400; font-size: 16px; }
+    /* ── Misc ── */
+    .diagram-status { color: var(--text-secondary); font-size: 13px; margin: 8px 0 0; }
+    .placeholder { color: var(--gray); font-style: italic; }
+    ul, ol { padding-left: 20px; }
+    li { margin: 4px 0; }
+    strong { font-weight: 600; }
+    /* ── Back to Top ── */
+    #back-to-top {
+      position: fixed; bottom: 28px; right: 28px;
+      padding: 8px 16px; border-radius: var(--radius);
+      background: var(--panel); color: var(--accent);
+      border: 1px solid var(--line); box-shadow: var(--shadow-md);
+      text-decoration: none; font-size: 13px; font-weight: 500;
+      opacity: 0; pointer-events: none;
+      transition: opacity 0.2s, box-shadow 0.2s;
+    }
+    #back-to-top:hover { box-shadow: var(--shadow-sm); }
+    #back-to-top.visible { opacity: 1; pointer-events: auto; }
+    /* ── Responsive ── */
     @media (max-width: 820px) {
       .layout { grid-template-columns: 1fr; }
-      nav { position: static; }
+      nav {
+        position: static;
+        height: auto;
+        border-right: none;
+        border-bottom: 1px solid var(--line);
+        padding: 12px;
+        display: flex;
+        gap: 4px;
+        overflow-x: auto;
+        scrollbar-width: none;
+      }
+      nav::-webkit-scrollbar { display: none; }
+      nav a { white-space: nowrap; padding: 6px 10px; }
+      nav a .nav-dot { display: none; }
+      header { padding: 28px 20px 20px; }
+      main { padding: 8px 20px 60px; }
+      #back-to-top { bottom: 12px; right: 12px; }
+    }
+    /* ── Print ── */
+    @media print {
+      nav, .controls-bar, #back-to-top, .no-results { display: none !important; }
+      .layout { grid-template-columns: 1fr; padding: 0; }
+      .card { box-shadow: none; break-inside: avoid; border: 1px solid #ddd; }
+      .diagram-card { box-shadow: none; }
+      body { background: #fff; }
+      header { background: #fff; padding: 20px 0; }
+      main { padding: 0; max-width: 100%; }
+      a { color: #333; }
+      code { color: #333; }
+      * { color-adjust: exact; -webkit-print-color-adjust: exact; }
     }
   </style>
 </head>
@@ -94,19 +411,26 @@
   </header>
   <div class="layout">
     <nav aria-label="Report sections">
-      <a href="#summary">Summary</a>
-      <a href="#architecture">Architecture</a>
-      <a href="#interfaces">Interfaces</a>
-      <a href="#requirements">Requirements</a>
-      <a href="#flows">Flows</a>
-      <a href="#security">Security</a>
-      <a href="#nonfunctional">Non-functional</a>
-      <a href="#questions">Open Questions</a>
-      <a href="#evidence">Evidence</a>
+      <a href="#summary"><span class="nav-dot"></span>Summary</a>
+      <a href="#architecture"><span class="nav-dot"></span>Architecture</a>
+      <a href="#interfaces"><span class="nav-dot"></span>Interfaces</a>
+      <a href="#requirements"><span class="nav-dot"></span>Requirements</a>
+      <a href="#flows"><span class="nav-dot"></span>Flows</a>
+      <a href="#domain"><span class="nav-dot"></span>Domain Model</a>
+      <a href="#security"><span class="nav-dot"></span>Security</a>
+      <a href="#errors"><span class="nav-dot"></span>Errors</a>
+      <a href="#nonfunctional"><span class="nav-dot"></span>Non-functional</a>
+      <a href="#questions"><span class="nav-dot"></span>Open Questions</a>
+      <a href="#evidence"><span class="nav-dot"></span>Evidence</a>
     </nav>
     <main>
       <div class="controls">
-        <input id="report-search" type="search" placeholder="Filter cards, APIs, modules, and evidence">
+        <div class="controls-bar">
+          <input id="report-search" type="search" placeholder="Search APIs, modules, evidence...">
+          <button id="toggle-details" type="button">Expand all</button>
+          <button id="show-questions" type="button">Questions only</button>
+        </div>
+        <p class="no-results" id="no-results">No matching content found.</p>
       </div>
       <section id="summary">
         <h2>Executive Summary</h2>
@@ -138,12 +462,24 @@
         <p class="placeholder">Pending flow diagrams.</p>
         <!-- /REQUIREMENTS_FLOWS -->
       </section>
+      <section id="domain">
+        <h2>Domain Model And Data Ownership</h2>
+        <!-- REQUIREMENTS_DOMAIN_MODEL -->
+        <p class="placeholder">Pending domain model and data ownership.</p>
+        <!-- /REQUIREMENTS_DOMAIN_MODEL -->
+      </section>
       <section id="security">
-        <h2>Security, Permissions, And Errors</h2>
+        <h2>Permissions, Security, And Compliance</h2>
         <!-- REQUIREMENTS_SECURITY -->
-        <p class="placeholder">Pending security and error notes.</p>
+        <p class="placeholder">Pending permissions, security, and compliance notes.</p>
         <!-- /REQUIREMENTS_SECURITY -->
       </section>
+      <section id="errors">
+        <h2>Error Handling And Edge Cases</h2>
+        <!-- REQUIREMENTS_ERROR_HANDLING -->
+        <p class="placeholder">Pending error handling and edge cases.</p>
+        <!-- /REQUIREMENTS_ERROR_HANDLING -->
+      </section>
       <section id="nonfunctional">
         <h2>Non-functional Requirements</h2>
         <!-- REQUIREMENTS_NONFUNCTIONAL -->
@@ -164,15 +500,81 @@
       </section>
     </main>
   </div>
+  <a href="#" id="back-to-top">Back to top</a>
   <script>
-    const search = document.querySelector('#report-search');
-    search?.addEventListener('input', () => {
-      const query = search.value.trim().toLowerCase();
-      for (const card of document.querySelectorAll('.card, details, table')) {
-        const matched = !query || card.textContent.toLowerCase().includes(query);
-        card.style.display = matched ? '' : 'none';
-      }
-    });
+    (() => {
+      const search = document.querySelector('#report-search');
+      const noResults = document.querySelector('#no-results');
+      const sections = document.querySelectorAll('section[id]');
+      const cards = document.querySelectorAll('.card, details');
+      const tables = document.querySelectorAll('table');
+      const navLinks = document.querySelectorAll('nav a');
+
+      /* ── Scroll spy ── */
+      const observer = new IntersectionObserver(entries => {
+        entries.forEach(e => {
+          if (e.isIntersecting) {
+            navLinks.forEach(l => l.classList.toggle('active', l.getAttribute('href') === '#' + e.target.id));
+          }
+        });
+      }, { rootMargin: '-80px 0px -70% 0px', threshold: 0 });
+      sections.forEach(s => observer.observe(s));
+
+      /* ── Search ── */
+      search?.addEventListener('input', () => {
+        const query = search.value.trim().toLowerCase();
+        let anyVisible = false;
+        if (!query) {
+          cards.forEach(c => c.style.display = '');
+          tables.forEach(t => t.style.display = '');
+          sections.forEach(s => s.style.display = '');
+          noResults.style.display = 'none';
+          return;
+        }
+        sections.forEach(s => {
+          const inner = s.querySelectorAll('.card, details, table');
+          let sectionVisible = false;
+          inner.forEach(el => {
+            const matched = el.textContent.toLowerCase().includes(query);
+            el.style.display = matched ? '' : 'none';
+            if (matched) sectionVisible = true;
+          });
+          s.style.display = sectionVisible ? '' : 'none';
+          if (sectionVisible) anyVisible = true;
+        });
+        noResults.style.display = anyVisible ? 'none' : 'block';
+      });
+
+      /* ── Expand / Collapse all ── */
+      const toggleBtn = document.querySelector('#toggle-details');
+      let allOpen = false;
+      toggleBtn?.addEventListener('click', () => {
+        allOpen = !allOpen;
+        document.querySelectorAll('details.card').forEach(d => d.open = allOpen);
+        toggleBtn.textContent = allOpen ? 'Collapse all' : 'Expand all';
+      });
+
+      /* ── Show questions only ── */
+      const questionsBtn = document.querySelector('#show-questions');
+      let questionsOnly = false;
+      questionsBtn?.addEventListener('click', () => {
+        questionsOnly = !questionsOnly;
+        const target = document.querySelector('#questions');
+        if (questionsOnly) {
+          sections.forEach(s => s.style.display = s === target ? '' : 'none');
+          questionsBtn.textContent = 'Show all sections';
+        } else {
+          sections.forEach(s => s.style.display = '');
+          questionsBtn.textContent = 'Questions only';
+        }
+      });
+
+      /* ── Back to top ── */
+      const backToTop = document.querySelector('#back-to-top');
+      window.addEventListener('scroll', () => {
+        backToTop?.classList.toggle('visible', window.scrollY > 400);
+      }, { passive: true });
+    })();
   </script>
 </body>
 </html>