Phase 4: Copilot governance layer

.github/agents/network-dashboard-implementer.md

@@ -0,0 +1,55 @@
+---
+name: network-dashboard-implementer
+description: "Specialized agent for implementing features in the PulseFabric Monitor dashboard. Follows strict implementation order and validates all 20 production code rules."
+---
+
+# Network Dashboard Implementer
+
+You are an expert Angular developer building features for **PulseFabric Monitor**, an enterprise infrastructure monitoring dashboard.
+
+## Planning
+
+Before writing any code, create a brief plan:
+
+1. Identify which phase of the implementation order applies: **db.json → model → service → UI**.
+2. List the files that will be created or modified.
+3. If more than 3 existing files must change, **stop and ask for confirmation**.
+
+## Implementation Rules
+
+You MUST comply with all 20 rules in `.github/copilot-instructions.md`. The critical ones are:
+
+- **No `any` type** — use typed interfaces from `core/models/api.models.ts`.
+- **No hardcoded data** — all data flows from `backend/db.json` through the API service.
+- **No magic numbers** — use constants, enums, or design tokens.
+- **CSS tokens only** — use `--mat-sys-*`, `--pf-*`, or SCSS variables. No raw hex/px/rem.
+- **Separate files** — TS, HTML, SCSS must be in separate files.
+- **Standalone components** — no NgModules.
+- **Reuse before creating** — check existing components before making new ones.
+- **No console.log** — remove all logging before completing.
+- **No dead code** — no commented-out blocks.
+
+## Repo Compliance
+
+Before completing any task, verify:
+
+- [ ] Implementation follows db.json → model → service → UI order
+- [ ] All interfaces defined in `api.models.ts`
+- [ ] All HTTP calls go through `DashboardApi` service
+- [ ] No component fetches data directly
+- [ ] All design tokens used correctly
+- [ ] SCSS nesting ≤ 3 levels
+- [ ] `ng build` passes
+
+## Validation
+
+After implementation, run `ng build` from the `frontend/` directory. The build must pass with zero errors. Budget warnings for echarts are acceptable.
+
+## Stop Behavior
+
+**Stop and ask the user** when:
+
+- The task requires modifying more than 3 existing files.
+- The task conflicts with any of the 20 rules.
+- The data shape in `db.json` is ambiguous or incomplete.
+- You are unsure whether to create a new component or extend an existing one.

.github/copilot-instructions.md

@@ -0,0 +1,122 @@
+# PulseFabric Monitor — Copilot Instructions
+
+## Project Overview
+
+PulseFabric Monitor is an enterprise infrastructure monitoring dashboard built with Angular 21, Angular Material (Material 3), and a json-server fake backend. The codebase lives under `/frontend` (Angular app) and `/backend` (db.json).
+
+## Feature Implementation Order
+
+When adding any new feature, **always** follow this sequence:
+
+1. **db.json** — Add or update the data shape in `backend/db.json`
+2. **Typed model** — Add or update the DTO interface in `frontend/src/app/core/models/api.models.ts`
+3. **Service** — Add a method to `frontend/src/app/core/services/dashboard-api.service.ts`
+4. **UI** — Build or extend the component, consuming data via the service
+
+Never skip steps. Never put data fetching logic directly in a component.
+
+## All Decisions Must Be Documented
+
+Before making any change, write a brief rationale in the commit message or PR description. If a decision involves trade-offs, document it explicitly.
+
+---
+
+## Twenty Production Code Rules
+
+Every line of code generated or modified **must** comply with all twenty rules below. Violations are not acceptable.
+
+### 1. Separation of Concerns
+TS, HTML, and SCSS must be in separate files. Frontend and backend are separate directories.
+
+### 2. No Hardcoded Data
+All data must come from mock files or API services. Never embed data literals in templates or component classes.
+
+### 3. Typed Interfaces for All Data
+Every data structure must have a TypeScript interface. The `any` type is **strictly forbidden** everywhere—function parameters, return types, variables, generics.
+
+### 4. Component-Driven Architecture
+All UI must be composed of reusable, standalone Angular components. No logic in `app.html` beyond a single root component tag.
+
+### 5. No Magic Numbers or Strings
+All values must be stored in named constants, enums, or configuration objects. No unexplained literals in code.
+
+### 6. CSS Token System
+All colors, spacing, border-radius, and typography must use Material 3 system variables (`--mat-sys-*`), project tokens (`--pf-*`), or SCSS variables. Never write raw hex, px, or rem values directly in component SCSS.
+
+### 7. Material 3 Compliance
+Follow Angular Material / Material 3 guidelines for spacing, typography, color, and component usage. Use `mat-card`, `mat-icon`, etc. from `@angular/material`.
+
+### 8. Concise, Idiomatic Angular
+Use signals, `input()`, `inject()`, pipes, and directives. Avoid verbose boilerplate. Prefer declarative patterns over imperative ones.
+
+### 9. No Over-Engineering
+Do not add state management libraries, unit test frameworks, authentication, or logging infrastructure unless explicitly requested. Keep it minimal.
+
+### 10. Reuse Before Creating
+Before creating any new component, service, or utility, audit existing code for reusable pieces. If an existing component can be extended via inputs, prefer that over creating a new one.
+
+### 11. Generic Component Design
+Components like KPI cards, chart widgets, and alert items must be input-driven. Adding a new instance of the same type should require only a single template reference with different inputs—no new component file.
+
+### 12. Minimal Change Principle
+If adding a feature requires modifying more than 3 existing files, **stop and explain** the scope before proceeding. Get confirmation before making broad changes.
+
+### 13. Flat HTML Structure
+No unnecessary DOM wrappers. Keep HTML structure as flat and semantic as possible. Every element must serve a layout or semantic purpose.
+
+### 14. No console.log
+Remove all `console.log`, `console.warn`, `console.error` statements before committing. Use proper error handling patterns instead.
+
+### 15. No Dead Code
+No commented-out code blocks. If code is not needed, delete it. Version control preserves history.
+
+### 16. Clean Imports
+Every import must be used. No orphan imports. Organize imports logically (Angular core → Angular Material → third-party → project).
+
+### 17. Consistent Naming Conventions
+- Files: `kebab-case` (e.g., `kpi-card.ts`)
+- Variables/functions: `camelCase`
+- Classes/interfaces: `PascalCase`
+- CSS classes: `kebab-case`
+
+### 18. Single Responsibility per File
+Each file does exactly one thing. One component per file, one service per file, one model group per file.
+
+### 19. No `any` Type (Reinforced)
+This rule is critical enough to state twice. `any` is forbidden in all positions: parameters, return types, generics, type assertions. Use `unknown` with type guards if needed.
+
+### 20. SCSS Nesting ≤ 3 Levels
+SCSS selectors must not nest deeper than 3 levels. Refactor into separate classes if nesting would exceed this limit.
+
+---
+
+## Project Structure Reference
+
+```
+backend/
+  db.json                         ← json-server database
+
+frontend/src/app/
+  core/
+    models/api.models.ts          ← All typed DTOs
+    services/dashboard-api.service.ts ← API abstraction layer
+    mocks/                        ← Legacy mock files (being phased out)
+  dashboard/
+    dashboard.ts / .html / .scss  ← Main dashboard page
+    kpi-card/                     ← Generic KPI card (input-driven)
+    chart-widget/                 ← Generic chart widget (input-driven)
+    alert-list/                   ← Alert list component
+    chart-config.factory.ts       ← Pure functions generating ECharts options
+  shared/styles/
+    _tokens.scss                  ← Design tokens (spacing, radius, etc.)
+  environments/
+    environment.ts                ← Dev config (apiBaseUrl)
+    environment.prod.ts           ← Prod config
+```
+
+## Key Patterns
+
+- **Chart addition**: Add factory function in `chart-config.factory.ts` → reference `<app-chart-widget>` in template with `[options]`
+- **KPI addition**: Add entry to `db.json` kpis array → `<app-kpi-card>` renders automatically via `@for`
+- **Alert addition**: Add entry to `db.json` alerts array → renders automatically
+- **API base URL**: Managed via `environment.ts` + Angular dev proxy (`proxy.conf.json`)

.github/prompts/add-chart-widget.prompt.md

@@ -0,0 +1,68 @@
+---
+mode: agent
+description: "Add a new chart widget to the PulseFabric Monitor dashboard"
+---
+
+# Demo: Add a Chart to AI Drop Zone
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+> Add a CPU Load by Device bar chart to the AI Widget Drop Zone at the bottom of the dashboard. Show 5 devices with fake CPU percentage data. Add the data to db.json first, then create the chart. Follow all repo rules in copilot-instructions.md.
+
+---
+
+## Task: Add a New Chart Widget
+
+Follow the strict implementation order. Do not skip any step.
+
+### Step 1 — db.json
+Open `backend/db.json` and add a new top-level collection for the chart data. Example:
+```json
+"myNewData": [
+  { "label": "A", "value": 10 },
+  { "label": "B", "value": 20 }
+]
+```
+
+### Step 2 — Typed Model
+Add the DTO interface to `frontend/src/app/core/models/api.models.ts`:
+```ts
+export interface MyNewDto {
+  label: string;
+  value: number;
+}
+```
+
+### Step 3 — Service Method
+Add a method to `frontend/src/app/core/services/dashboard-api.service.ts`:
+```ts
+getMyNewData(): Observable<MyNewDto[]> {
+  return this.http.get<MyNewDto[]>(`${this.base}/myNewData`);
+}
+```
+
+### Step 4 — Chart Factory Function
+Add a pure function in `frontend/src/app/dashboard/chart-config.factory.ts`:
+```ts
+export function buildMyNewChartOption(data: MyNewDto[]): EChartsOption {
+  // Use PALETTE constants for colors.
+  // Return a complete EChartsOption object.
+}
+```
+Colors MUST come from the `PALETTE` constant — no raw hex in the function.
+
+### Step 5 — Dashboard Integration
+In `frontend/src/app/dashboard/dashboard.ts`:
+- Import the new factory function and DTO.
+- Add a signal for the chart options.
+- Call the new service method inside the existing `forkJoin` block.
+
+In `frontend/src/app/dashboard/dashboard.html`:
+- Add a `<app-chart-widget>` reference with `[title]` and `[options]`.
+
+**Do NOT create a new component.** Use the existing `ChartWidget` with different inputs.
+
+### Validation
+- Run `ng build` — must pass.
+- Confirm the chart renders in the browser.
+- Confirm no `console.log`, no `any`, no magic numbers, SCSS ≤ 3 levels.

.github/prompts/add-kpi-widget.prompt.md

@@ -0,0 +1,44 @@
+---
+mode: agent
+description: "Add a new KPI widget to the PulseFabric Monitor dashboard"
+---
+
+# Demo: Add a KPI Card
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+> Add a new KPI card called Active Sessions showing the number 14,200 with a trending up indicator. Put it next to the existing KPI cards. Follow all repo rules in copilot-instructions.md.
+
+---
+
+## Task: Add a New KPI Widget
+
+Follow the strict implementation order below. Do not skip any step.
+
+### Step 1 — db.json
+Open `backend/db.json` and add a new entry to the `kpis` array:
+```json
+{
+  "id": "<kebab-case-id>",
+  "title": "<Display Title>",
+  "value": "<string value>",
+  "unit": "<optional unit>",
+  "trend": "up | down | stable",
+  "trendLabel": "<human-readable trend>",
+  "icon": "<Material Icon name>"
+}
+```
+
+### Step 2 — Verify Typed Model
+Ensure `KpiDto` in `frontend/src/app/core/models/api.models.ts` already covers the shape. If new fields are needed, add them to the interface.
+
+### Step 3 — Verify Service
+Confirm `DashboardApi.getKpis()` in `frontend/src/app/core/services/dashboard-api.service.ts` already returns `Observable<KpiDto[]>`. No change should be needed.
+
+### Step 4 — UI (Automatic)
+Because the dashboard template uses `@for (kpi of kpis(); track kpi.title)` with `<app-kpi-card>`, the new KPI renders automatically. **No component code changes required.**
+
+### Validation
+- Run `ng build` — must pass with no errors.
+- Confirm the new KPI card appears in the browser.
+- Confirm no `console.log`, no `any` type, no hardcoded values.

.github/prompts/add-new-component.prompt.md

@@ -0,0 +1,60 @@
+---
+mode: agent
+description: "Add a new standalone component to the PulseFabric Monitor dashboard"
+---
+
+# Demo: Add a Brand New Widget
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+> Add a new AI Security Recommendations widget to the dashboard. It should show 3 recommendations, each with a priority level (High, Medium, Low) and a short description. Add the data to db.json first, then build the component. Follow all repo rules in copilot-instructions.md.
+
+---
+
+## Task: Add a New Component
+
+Before creating anything, answer these questions:
+
+1. **Can an existing component handle this?** Check `kpi-card`, `chart-widget`, and `alert-list` first. If the new feature fits one of these patterns, extend via inputs — do not create a new component.
+2. **Will this modify more than 3 existing files?** If yes, stop and explain the scope before proceeding.
+
+If a new component is genuinely needed, follow the steps below.
+
+### Step 1 — db.json
+Add the backing data to `backend/db.json` as a new collection.
+
+### Step 2 — Typed Model
+Add the DTO interface to `frontend/src/app/core/models/api.models.ts`.
+
+### Step 3 — Service Method
+Add a method to `frontend/src/app/core/services/dashboard-api.service.ts` returning `Observable<YourDto[]>`.
+
+### Step 4 — Create Component
+Create under `frontend/src/app/dashboard/<component-name>/`:
+```
+<component-name>.ts
+<component-name>.html
+<component-name>.scss
+```
+
+Requirements:
+- **Standalone component** — no NgModule.
+- **TS / HTML / SCSS in separate files** — no inline templates or styles.
+- **Input-driven** — accept data via `input()` signals, not internal fetching.
+- **Use Material 3 tokens** — `--mat-sys-*` and `--pf-*` for all visual values.
+- **Flat HTML** — no unnecessary `<div>` wrappers.
+- **SCSS nesting ≤ 3 levels**.
+- **No `any` type anywhere**.
+
+### Step 5 — Wire into Dashboard
+In `dashboard.ts`:
+- Import the new component, add to `imports` array.
+- Fetch data via the service; store in a signal.
+
+In `dashboard.html`:
+- Add the component tag with `[input]` bindings.
+
+### Step 6 — Validation
+- `ng build` must pass.
+- No `console.log`, no dead code, no unused imports.
+- Naming: file = `kebab-case`, class = `PascalCase`, variables = `camelCase`.

.github/skills/dashboard-widget.md

@@ -0,0 +1,42 @@
+---
+name: dashboard-widget
+description: "(Optional) Skill for scaffolding dashboard widgets following PulseFabric conventions"
+optional: true
+---
+
+# Dashboard Widget Skill
+
+This skill provides step-by-step scaffolding for adding widgets to the PulseFabric Monitor dashboard.
+
+## When to Use
+
+Use this skill when:
+- Adding a new KPI card (data-only change in `db.json`)
+- Adding a new chart widget (factory function + template reference)
+- Adding a new list or table widget (new component if no existing one fits)
+
+## Widget Types
+
+### KPI Card (no new component needed)
+1. Add entry to `kpis` array in `backend/db.json`
+2. Verify `KpiDto` interface covers the shape
+3. Card renders automatically via `@for` loop
+
+### Chart Widget (no new component needed)
+1. Add data collection to `backend/db.json`
+2. Add DTO to `api.models.ts`
+3. Add service method to `dashboard-api.service.ts`
+4. Add factory function to `chart-config.factory.ts`
+5. Add `<app-chart-widget>` in `dashboard.html` with `[title]` and `[options]`
+
+### Custom Widget (new component)
+1. Follow the full db.json → model → service → UI flow
+2. Create standalone component under `frontend/src/app/dashboard/`
+3. Must be input-driven, use Material 3 tokens, separate files
+
+## Conventions
+
+- Chart colors: use `PALETTE` from `chart-config.factory.ts`
+- Icons: use Material Icons (e.g., `speed`, `warning`, `cloud`)
+- Spacing: use `--pf-space-*` tokens
+- Border radius: use `--pf-radius-*` tokens

README.md

@@ -16,3 +16,23 @@ This project rearchitects the B2B Design-to-Code workflow, eliminating complex l
 3. Click **Create codespace on main**.
 4. Wait for the Dev Container to build — Node.js 20, Angular CLI, and all VS Code extensions will be installed automatically.
 5. Once the terminal is ready, you're good to go.
+
+
+Use cases AI prompts
+# Demo: Add a KPI Card
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+"Add a new KPI card called Active Sessions showing the number 14,200 with a trending up indicator. Put it next to the existing KPI cards. Follow all repo rules in copilot-instructions.md."
+
+# Demo: Add a Chart to AI Drop Zone
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+"Add a CPU Load by Device bar chart to the AI Widget Drop Zone at the bottom of the dashboard. Show 5 devices with fake CPU percentage data. Add the data to db.json first, then create the chart. Follow all repo rules in copilot-instructions.md."
+
+# Demo: Add a Brand New Widget
+
+Use this prompt during live demo. Copy and paste the sentence below into Copilot Chat:
+
+"Add a new AI Security Recommendations widget to the dashboard. It should show 3 recommendations, each with a priority level (High, Medium, Low) and a short description. Add the data to db.json first, then build the component. Follow all repo rules in copilot-instructions.md."

docs/ai-working-rules.md

@@ -0,0 +1,72 @@
+# AI Working Rules — PulseFabric Monitor
+
+This document defines the rules and conventions that AI assistants (GitHub Copilot, agents, etc.) must follow when working on this project.
+
+## Feature Implementation Order
+
+All features must be implemented in this strict sequence:
+
+1. **db.json** — Add or update data in `backend/db.json`
+2. **Typed model** — Add or update the DTO interface in `frontend/src/app/core/models/api.models.ts`
+3. **Service** — Add a method to `frontend/src/app/core/services/dashboard-api.service.ts`
+4. **UI** — Build or extend the component, consuming data via the service
+
+Never skip steps. Never put data fetching logic directly in a component.
+
+## 20 Production Code Rules
+
+| # | Rule | Summary |
+|---|------|---------|
+| 1 | Separation of Concerns | TS, HTML, SCSS in separate files |
+| 2 | No Hardcoded Data | All data from API or mock files |
+| 3 | Typed Interfaces | Every data structure has a TS interface; `any` is forbidden |
+| 4 | Component-Driven | Reusable standalone Angular components |
+| 5 | No Magic Numbers | Named constants, enums, or config objects only |
+| 6 | CSS Token System | Use `--mat-sys-*`, `--pf-*`, or SCSS variables |
+| 7 | Material 3 Compliance | Follow M3 guidelines for all UI |
+| 8 | Concise Angular | Signals, `input()`, `inject()`, pipes, directives |
+| 9 | No Over-Engineering | No unnecessary libraries or infrastructure |
+| 10 | Reuse Before Creating | Audit existing code first |
+| 11 | Generic Component Design | Input-driven; new instance = new inputs, not new file |
+| 12 | Minimal Change Principle | >3 files changed → stop and explain |
+| 13 | Flat HTML Structure | No unnecessary DOM wrappers |
+| 14 | No console.log | Remove all logging before committing |
+| 15 | No Dead Code | No commented-out blocks |
+| 16 | Clean Imports | Every import must be used |
+| 17 | Consistent Naming | kebab-case files, camelCase vars, PascalCase classes |
+| 18 | Single Responsibility | One component/service/model group per file |
+| 19 | No `any` (Reinforced) | Forbidden in all positions |
+| 20 | SCSS Nesting ≤ 3 Levels | Refactor into separate classes if exceeded |
+
+## Governance Files
+
+| File | Purpose |
+|------|---------|
+| `.github/copilot-instructions.md` | Full rule set loaded into every Copilot session |
+| `.github/prompts/add-kpi-widget.prompt.md` | Step-by-step prompt for adding a KPI card |
+| `.github/prompts/add-chart-widget.prompt.md` | Step-by-step prompt for adding a chart widget |
+| `.github/prompts/add-new-component.prompt.md` | Step-by-step prompt for creating a new component |
+| `.github/agents/network-dashboard-implementer.md` | Agent profile with planning, compliance, and stop behavior |
+| `.github/skills/dashboard-widget.md` | Optional skill for widget scaffolding |
+
+## Stop Conditions
+
+The AI must stop and ask the user when:
+
+- A task requires modifying more than 3 existing files
+- A task conflicts with any of the 20 rules
+- The data shape is ambiguous or incomplete
+- It is unclear whether to create or reuse a component
+
+## Validation Checklist
+
+Before completing any task, verify:
+
+- [ ] `ng build` passes from `frontend/`
+- [ ] No `any` types introduced
+- [ ] No `console.log` statements
+- [ ] No dead or commented-out code
+- [ ] All imports are used
+- [ ] SCSS nesting ≤ 3 levels
+- [ ] CSS tokens used (no raw hex/px/rem)
+- [ ] Implementation follows db.json → model → service → UI order