From f7e63c4d5a91f3baed5c35016d87ed11f5a94bbd Mon Sep 17 00:00:00 2001
From: Matus Kasak <matus.kasak@dataquest.sk>
Date: Wed, 25 Feb 2026 16:24:54 +0100
Subject: [PATCH 1/2] First version of agents.md

---
 docs/agents.md | 434 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 434 insertions(+)
 create mode 100644 docs/agents.md

diff --git a/docs/agents.md b/docs/agents.md
new file mode 100644
index 00000000000..7cd073a7437
--- /dev/null
+++ b/docs/agents.md
@@ -0,0 +1,434 @@
+# DSpace Angular – Agent & User Guide
+
+> **Audience**: AI coding agents (GitHub Copilot, Cursor, etc.) **and** humans who delegate issues to them.
+> Covers the exact steps a user must do manually, the prompt to give the agent, what the agent must do, and hard-won lessons from real CI failures.
+
+---
+
+## 1. Project Facts
+
+| Property | Value |
+|----------|-------|
+| Framework | Angular 15 + Angular Universal (SSR) |
+| Language | TypeScript 4.8 |
+| Package manager | **Yarn 1.x** — never use `npm` |
+| Node.js | **18.x** (`nvm use 18`) — Node 20+ breaks `eslint-plugin-jsdoc` |
+| Unit tests | Jasmine / Karma (~5 300 specs, ~3.5 min) |
+| E2E tests | Cypress 13, Chrome headless |
+| Main branch | `dtq-dev` |
+| CI file | `.github/workflows/build.yml` |
+| Repo | `dataquest-dev/dspace-angular` |
+
+---
+
+## 2. User Checklist — What YOU Must Do Before the Agent Starts
+
+The agent cannot start Docker, install nvm, or open VS Code for you. Do these steps **once** per machine / session.
+
+### 2.1 One-time Setup
+
+1. Install **Docker Desktop** and start it.
+2. Install **nvm** (or nvm-windows) and run:
+   ```bash
+   nvm install 18
+   nvm use 18
+   ```
+3. Install Yarn globally: `npm install -g yarn`
+4. Clone the repo (if not done):
+   ```bash
+   git clone https://github.com/dataquest-dev/dspace-angular.git
+   cd dspace-angular
+   ```
+
+### 2.2 Before Every Agent Session
+
+1. **Start the DSpace backend in Docker** (needed for e2e tests):
+   ```bash
+   docker compose -p ci -f docker/docker-compose-ci.yml up -d
+   docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
+   ```
+   Wait until `docker container ls` shows all containers healthy.
+   Verify: `curl http://localhost:8080/server/api/core/sites` returns JSON.
+
+2. **Ensure correct Node version** — `node --version` must say `v18.x`.
+
+3. **Set the heap size** (prevents OOM on build):
+   - PowerShell: `$env:NODE_OPTIONS='--max-old-space-size=4096'`
+   - Bash: `export NODE_OPTIONS='--max-old-space-size=4096'`
+
+4. **Install dependencies**:
+   ```bash
+   yarn install --frozen-lockfile
+   ```
+   If Cypress download fails: `CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile`
+
+5. **Open the project in VS Code** (or your editor).
+
+6. **Create a feature branch**:
+   ```bash
+   git checkout dtq-dev && git pull
+   git checkout -b ufal/<short-issue-description>
+   ```
+
+### 2.3 Giving the Issue to the Agent
+
+Paste the agent a prompt like this (adapt the issue URL and description):
+
+> Here is the issue: `<LINK TO GITHUB ISSUE>`
+> Here is the agent guide: `docs/agents.md`
+>
+> Please read the guide first, then implement the fix, and iterate through **every CI step**
+> (lint → circ-deps → build → unit tests → e2e tests) until all pass.
+> Only then commit and push to the branch `ufal/<branch-name>`.
+> If e2e tests fail on known pre-existing issues, that is acceptable — see the guide.
+
+That's it. The rest is the agent's job.
+
+---
+
+## 3. The CI Pipeline (`build.yml`)
+
+Every PR triggers CI on Node 18.x and 20.x. **All steps must pass.**
+
+| # | Step | Command | Time |
+|---|------|---------|------|
+| 1 | Install | `yarn install --frozen-lockfile` | ~2 min |
+| 2 | Lint | `yarn run lint --quiet` | ~76 sec |
+| 3 | Circular deps | `yarn run check-circ-deps` | ~34 sec |
+| 4 | Build (browser + server) | `yarn run build:prod` | ~6.5 min |
+| 5 | Unit tests | `yarn run test:headless` | ~3.5 min |
+| 6 | Docker backend up | `docker compose -f docker/docker-compose-ci.yml up -d` + assetstore | ~3 min |
+| 7 | E2E tests | `yarn run serve:ssr` + Cypress via `cypress-io/github-action` | ~5 min |
+| 8 | SSR verification | `wget` + `grep` on 10 entity pages (Home, Community, Collection, Publication, Person, Project, OrgUnit, Journal, Journal Volume, Journal Issue) | ~1 min |
+| 9 | HTTP status codes | 301 `/handle/*`, 403, 404, 500 | ~30 sec |
+
+---
+
+## 4. Agent Workflow — Step-by-Step Iteration
+
+### ⚠️ RULE: Do NOT commit or push until steps 1–5 all pass. Steps 6–7 if Docker backend is available.
+
+```
+FOR EACH step below:
+  1. Run the command
+  2. If it FAILS → fix the code → rerun THAT SAME step
+  3. Only proceed to the next step when current one is green
+```
+
+### Step 1 — Install Dependencies
+```bash
+yarn install --frozen-lockfile
+```
+
+### Step 2 — Lint
+```bash
+yarn run lint --quiet
+```
+Must exit with code 0 and print "All files pass linting."
+
+### Step 3 — Circular Dependencies
+```bash
+yarn run check-circ-deps
+```
+Must print "✔ No circular dependency found!"
+
+**⚠️ PowerShell trap**: The underlying `madge --exclude` regex contains `|` pipe characters. PowerShell interprets `|` as a pipeline operator even inside quotes. Use the stop-parsing token:
+```powershell
+npx --% madge --exclude "(bitstream|bundle|collection|config-submission-form|eperson|item|version)\.model\.ts$" --circular --extensions ts ./
+```
+
+### Step 4 — Production Build
+```bash
+yarn run build:prod
+```
+Takes ~6.5 min. Run as a background process and poll for completion.
+Must produce **two** successful bundles: browser + server. Ignore warnings about unused theme components and CommonJS dependencies — these are pre-existing.
+
+### Step 5 — Unit Tests
+```bash
+yarn run test:headless
+```
+Expect ~5 300 specs, 0 failures. If a test fails, read the error, fix the code or test, rerun.
+
+Run a single test file:
+```bash
+yarn run test:headless --include='**/path/to/component.spec.ts'
+```
+
+### Step 6 — E2E Tests (requires Docker backend)
+
+Start the SSR server first (if not already running):
+```bash
+yarn run serve:ssr &          # background
+# Wait for http://localhost:4000 to respond
+```
+
+Run safe public-page specs (no login, no specific test data required):
+```bash
+npx cypress run --spec "cypress/e2e/footer.cy.ts,cypress/e2e/header.cy.ts,cypress/e2e/pagenotfound.cy.ts,cypress/e2e/browse-by-title.cy.ts,cypress/e2e/browse-by-author.cy.ts,cypress/e2e/browse-by-subject.cy.ts,cypress/e2e/community-list.cy.ts,cypress/e2e/search-page.cy.ts,cypress/e2e/feedback.cy.ts,cypress/e2e/browse-by-dateissued.cy.ts" --browser chrome
+```
+
+On Windows PowerShell, set the base URL first:
+```powershell
+$env:CYPRESS_BASE_URL="http://localhost:4000"
+npx cypress run --spec "cypress/e2e/footer.cy.ts,..." --browser chrome
+```
+
+### Step 7 — Commit & Push (only after all green)
+
+```bash
+git add <files>                 # NEVER add config/config.yml or .env.* files
+git commit -m "fix: <description>"
+git push origin ufal/<branch-name>
+```
+
+---
+
+## 5. E2E Test Categories & What to Run
+
+| Category | Spec files | Requires |
+|----------|-----------|----------|
+| **Public pages** (always safe) | `footer`, `header`, `pagenotfound`, `browse-by-*`, `community-list`, `search-page`, `feedback` | Frontend only |
+| **Data-dependent** | `collection-page`, `community-page`, `item-page` | Backend + Demo Entities assetstore |
+| **Login-required** | `submission*`, `admin-*`, `my-dspace`, `profile-page`, `handle-page`, `health-page`, `tombstone`, `system-wide-alert` | Backend + Demo Entities + valid credentials |
+| **No active tests** | `homepage`, `homepage-statistics`, `search-navbar`, `login-modal` | N/A |
+
+### Cypress Config
+
+- Config: `cypress.config.ts`
+- Specs: `cypress/e2e/*.cy.ts`
+- Default base URL: `http://localhost:4000` (override with `CYPRESS_BASE_URL`)
+- Retries: 2 in run mode, 0 in open mode
+- Test data: [Demo Entities Data set](https://github.com/DSpace-Labs/AIP-Files/releases/tag/demo-entities-data)
+
+### Key Test Variables (from `cypress.config.ts`)
+
+| Variable | Value |
+|----------|-------|
+| `DSPACE_TEST_ADMIN_USER` | `dspacedemo+admin@gmail.com` |
+| `DSPACE_TEST_ADMIN_PASSWORD` | `dspace` |
+| `DSPACE_TEST_COMMUNITY` | `0958c910-2037-42a9-81c7-dca80e3892b4` |
+| `DSPACE_TEST_COLLECTION` | `282164f5-d325-4740-8dd1-fa4d6d3e7200` |
+| `DSPACE_TEST_ENTITY_PUBLICATION` | `6160810f-1e53-40db-81ef-f6621a727398` |
+
+---
+
+## 6. Known Pre-existing E2E Failures (Not Your Bug)
+
+Before panicking about a red test, check this list:
+
+| Symptom | Affected Specs | Root Cause | Action |
+|---------|---------------|------------|--------|
+| `cy.get('.discojuice_close').click()` fails — element is `display: none` | All login-dependent tests | DiscoJuice popup is hidden in Docker env | **Skip** — pre-existing |
+| `cy.wait('@viewevent')` timeout | `collection-page.cy.ts` | Matomo/statistics not configured in Docker | **Skip** — pre-existing |
+| Entity redirect fails | `item-page.cy.ts` | Backend entity routing not configured | **Skip** — pre-existing |
+| `link-in-text-block` a11y violation | `privacy.cy.ts`, `end-user-agreement.cy.ts` | CSS link styling issue | **Skip** — pre-existing |
+
+**Rule**: Only fix failures that YOUR changes caused. If a test was already failing on `dtq-dev`, leave it alone.
+
+---
+
+## 7. Hard-Won Lessons (Pitfalls & Traps)
+
+These come from real agent sessions. Read them before writing code.
+
+### 7.1 Angular Template Binding
+
+❌ **WRONG** — interpolation inside `aria-*` / `attr.*`:
+```html
+<div aria-labelledby="prefix-{{ variable }}">
+```
+Angular will throw `Can't bind to 'aria-labelledby' since it isn't a known property` at build time.
+
+✅ **CORRECT** — property binding:
+```html
+<div [attr.aria-labelledby]="'prefix-' + variable">
+```
+
+This applies to **all** `aria-*` and custom HTML attributes. Always use `[attr.X]="expression"` instead of `X="{{ interpolation }}"` for non-standard attributes.
+
+### 7.2 Dynamic HTML IDs Must Be Valid
+
+HTML `id` attributes must not contain whitespace or special characters. If an ID is built from dynamic data (e.g., bundle names, file names, user input), **sanitize it**:
+
+```typescript
+sanitizedName = rawName.replace(/\s+/g, '');
+```
+
+Then use `sanitizedName` in the template `id` attribute. Never trust that a service will return a "safe" string for an HTML ID.
+
+### 7.3 Conditional `aria-describedby`
+
+If a `<label>` or description element is conditionally rendered (`*ngIf`), the `aria-describedby` pointing to it must also be conditional:
+
+```html
+<!-- The label only exists when `label` is truthy -->
+<span *ngIf="label" [id]="'desc-' + uniqueId">{{ label }}</span>
+
+<!-- So aria-describedby must be conditional too -->
+<input [attr.aria-describedby]="label ? 'desc-' + uniqueId : null">
+```
+
+If you always set `aria-describedby` to a non-existent element, screen readers will be confused and accessibility audits (Cypress axe-core) may flag it.
+
+### 7.4 Never Change Form Element IDs Unless You Have To
+
+Submission forms use IDs like `input#dc_title`, `label[for=local_hasCMDI]` etc. These are referenced by:
+- Cypress e2e selectors in `cypress/e2e/submission*.cy.ts`
+- `formModel` definitions in `src/app/shared/form/builder/`
+- DynamicFormControlLayout configs
+
+If you change these IDs (e.g., adding suffixes for uniqueness), **every Cypress selector breaks**. Unless the issue specifically requires changing form IDs, leave them alone.
+
+### 7.5 PowerShell-Specific Issues
+
+| Issue | Solution |
+|-------|---------|
+| `yarn run check-circ-deps` fails with pipe error | Use `npx --%` stop-parsing token (see Step 3 above) |
+| Environment variables don't persist across commands | Set them on the same line or use `$env:VAR='val'` before each command |
+| `&&` is not valid in PowerShell 5.1 | Use `;` to chain commands |
+
+### 7.6 Build Output — What to Ignore vs. What Matters
+
+**Ignore** (pre-existing, harmless):
+- `Warning: X.component.ts is part of the TypeScript compilation but it's unused`
+- `Warning: CommonJS or AMD dependencies can cause optimization bailouts`
+- `Warning: bundle initial exceeded maximum budget`
+- `Warning: Expected identifier but found "*"` (CSS hack for old IE)
+
+**Do NOT ignore** (real errors):
+- `Error: ...` lines in the build output
+- `Template parse errors`
+- `Property 'X' does not exist on type 'Y'`
+- `Module not found`
+
+### 7.7 Files You Must NEVER Commit
+
+| File | Reason |
+|------|--------|
+| `.env.*` files | Local environment configs |
+| `cypress/videos/`, `cypress/screenshots/` | Test artifacts |
+| `coverage/` | Generated coverage reports |
+
+### 7.8 Reverting a Bad Approach
+
+If your change looks correct but breaks dozens of tests, **stop and reconsider**. It's cheaper to revert a whole approach than to chase 50 cascading failures. Example: Adding unique ID suffixes to dynamic form elements broke all Cypress `input#dc_*` selectors — the right move was to revert the form changes entirely and fix only the static duplicates.
+
+### 7.9 Unit Test Spec Selectors
+
+When changing an `id`, `class`, or tag in a template, **always check the corresponding `.spec.ts` file**:
+```bash
+# Find the spec for a component
+ls src/app/.../my-component.component.spec.ts
+
+# Search for selectors that reference the changed ID/class
+grep -n "By.css" src/app/.../my-component.component.spec.ts
+```
+If a test uses `By.css('[id^="oldPrefix"]')` and you removed that ID, update the selector or the test will fail.
+
+---
+
+## 8. Docker Reference
+
+### Compose Files (`docker/`)
+
+| File | Purpose |
+|------|---------|
+| `docker-compose-ci.yml` | CI backend (DSpace REST + PostgreSQL + Solr) |
+| `docker-compose.yml` | Full stack dev |
+| `docker-compose-rest.yml` | REST backend only |
+| `cli.yml` | DSpace CLI commands |
+| `cli.assetstore.yml` | Load Demo Entities test data |
+
+### Default CI Ports
+
+| Service | Port |
+|---------|------|
+| DSpace REST API | 8080 |
+| PostgreSQL | 5432 |
+| Solr | 8983 |
+| Angular Frontend (SSR) | 4000 |
+
+### Docker Commands
+
+```bash
+# Start
+docker compose -p ci -f docker/docker-compose-ci.yml up -d
+docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
+
+# Verify
+docker container ls
+curl http://localhost:8080/server/api/core/sites
+
+# Stop
+docker compose -p ci -f docker/docker-compose-ci.yml down
+```
+
+---
+
+## 9. Common Errors & Solutions
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `The engine "node" is incompatible` | Node 20+ | `nvm use 18` |
+| `The Cypress App could not be downloaded` | Network | `CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile` |
+| Out of memory during build | Heap too small | `$env:NODE_OPTIONS='--max-old-space-size=4096'` |
+| Merge conflicts in `yarn.lock` | Branch diverged | `git checkout --theirs yarn.lock; yarn install; git add yarn.lock` |
+| `Can't bind to 'aria-labelledby'` | Template syntax | Use `[attr.aria-labelledby]="'...' + var"` not `aria-labelledby="...{{ var }}"` |
+| `Property 'X' does not exist on type` | Missing property | Add the property to the component class or fix the type |
+| Cypress can't connect | Frontend not running | Run `yarn run serve:ssr` first; check `CYPRESS_BASE_URL` |
+| `cy.wait()` timed out | Backend endpoint unavailable | Ensure Docker backend is up + assetstore loaded |
+| Docker images won't pull | Auth issue | `docker login ghcr.io` or check VPN/firewall |
+| `madge` pipe error on PowerShell | `|` in regex | Use `npx --%` stop-parsing token |
+| Test fails with `Cannot find element with id "..."` | You renamed/removed an ID | Update the test selector too |
+
+---
+
+## 10. Code Conventions
+
+| Convention | Rule |
+|------------|------|
+| Component prefix | `ds-` (e.g., `<ds-navbar>`) |
+| File naming | `*.component.ts`, `*.service.ts`, `*.model.ts`, `*.spec.ts`, `*.module.ts` |
+| Strings | Single quotes |
+| Indentation | 2 spaces |
+| Imports | Avoid barrel imports; import from specific files |
+| Lodash | Method imports: `import get from 'lodash/get'` |
+| SSR | All code must work with Angular Universal (no `document`/`window` without checks) |
+| Tests | Co-located with source (same directory, `.spec.ts` suffix) |
+| JSDoc | All new public methods and classes require TypeDoc comments |
+
+---
+
+## 11. Quick Reference
+
+```bash
+# === Setup ===
+nvm use 18
+yarn install --frozen-lockfile
+
+# === Full CI validation (run in this order) ===
+yarn run lint --quiet              # ~76 sec
+yarn run check-circ-deps           # ~34 sec
+yarn run build:prod                # ~6.5 min
+yarn run test:headless             # ~3.5 min
+
+# === Single unit test ===
+yarn run test:headless --include='**/path/to/test.spec.ts'
+
+# === Dev server (hot reload) ===
+yarn run start:dev                 # http://localhost:4000
+
+# === E2E tests ===
+docker compose -p ci -f docker/docker-compose-ci.yml up -d
+docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
+yarn run build:prod
+yarn run serve:ssr &
+yarn run e2e                       # all specs
+# or specific:
+npx cypress run --spec "cypress/e2e/footer.cy.ts" --browser chrome
+
+# === Cleanup ===
+docker compose -p ci -f docker/docker-compose-ci.yml down
+yarn run clean:prod
+```

From 03e534b0cd11c33589e4deaf7c2089c6fe1f461d Mon Sep 17 00:00:00 2001
From: Matus Kasak <matus.kasak@dataquest.sk>
Date: Wed, 4 Mar 2026 17:45:09 +0100
Subject: [PATCH 2/2] Updated agents.md script

---
 docs/agents.md | 519 +++++++++++++++++++++++++++----------------------
 1 file changed, 289 insertions(+), 230 deletions(-)

diff --git a/docs/agents.md b/docs/agents.md
index 7cd073a7437..3dfd36e8173 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -1,7 +1,11 @@
-# DSpace Angular – Agent & User Guide
+# DSpace Angular – Agent & Human Collaboration Guide
 
-> **Audience**: AI coding agents (GitHub Copilot, Cursor, etc.) **and** humans who delegate issues to them.
-> Covers the exact steps a user must do manually, the prompt to give the agent, what the agent must do, and hard-won lessons from real CI failures.
+> **Purpose**: A universal playbook for fixing **any** frontend issue through AI agent + human collaboration.
+> The human prepares the environment and provides the issue. The agent investigates the problem visually
+> (Playwright MCP), implements the fix, verifies it, and iterates until all CI checks pass.
+>
+> **Architecture**: Only the Angular frontend runs locally (for hot reload and code changes).
+> The backend services (DSpace REST API, PostgreSQL, Solr) run in Docker containers.
 
 ---
 
@@ -13,46 +17,43 @@
 | Language | TypeScript 4.8 |
 | Package manager | **Yarn 1.x** — never use `npm` |
 | Node.js | **18.x** (`nvm use 18`) — Node 20+ breaks `eslint-plugin-jsdoc` |
-| Unit tests | Jasmine / Karma (~5 300 specs, ~3.5 min) |
+| Unit tests | Jasmine / Karma (~5 300 specs) |
 | E2E tests | Cypress 13, Chrome headless |
 | Main branch | `dtq-dev` |
-| CI file | `.github/workflows/build.yml` |
 | Repo | `dataquest-dev/dspace-angular` |
 
 ---
 
-## 2. User Checklist — What YOU Must Do Before the Agent Starts
-
-The agent cannot start Docker, install nvm, or open VS Code for you. Do these steps **once** per machine / session.
+## 2. Human Setup — Do This Before Handing Off to the Agent
 
-### 2.1 One-time Setup
+### 2.1 One-Time Setup
 
 1. Install **Docker Desktop** and start it.
-2. Install **nvm** (or nvm-windows) and run:
+2. Install **nvm** (or nvm-windows):
    ```bash
    nvm install 18
    nvm use 18
    ```
-3. Install Yarn globally: `npm install -g yarn`
-4. Clone the repo (if not done):
+3. Install Yarn: `npm install -g yarn`
+4. Clone the repo:
    ```bash
    git clone https://github.com/dataquest-dev/dspace-angular.git
    cd dspace-angular
    ```
 
-### 2.2 Before Every Agent Session
+### 2.2 Before Every Session
 
-1. **Start the DSpace backend in Docker** (needed for e2e tests):
+1. **Start the backend services in Docker** (REST API, PostgreSQL, Solr — needed for e2e and live verification):
    ```bash
    docker compose -p ci -f docker/docker-compose-ci.yml up -d
    docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
    ```
-   Wait until `docker container ls` shows all containers healthy.
    Verify: `curl http://localhost:8080/server/api/core/sites` returns JSON.
+   > The frontend is NOT started here — it runs locally (see §3).
 
-2. **Ensure correct Node version** — `node --version` must say `v18.x`.
+2. **Node version**: `node --version` → must be `v18.x`
 
-3. **Set the heap size** (prevents OOM on build):
+3. **Heap size** (prevents OOM):
    - PowerShell: `$env:NODE_OPTIONS='--max-old-space-size=4096'`
    - Bash: `export NODE_OPTIONS='--max-old-space-size=4096'`
 
@@ -62,292 +63,356 @@ The agent cannot start Docker, install nvm, or open VS Code for you. Do these st
    ```
    If Cypress download fails: `CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile`
 
-5. **Open the project in VS Code** (or your editor).
-
-6. **Create a feature branch**:
+5. **Create a feature branch**:
    ```bash
    git checkout dtq-dev && git pull
-   git checkout -b ufal/<short-issue-description>
+   git checkout -b <dspace-customer>/<short-issue-description>
    ```
 
-### 2.3 Giving the Issue to the Agent
+6. **Open the project in VS Code** with Copilot / agent enabled.
 
-Paste the agent a prompt like this (adapt the issue URL and description):
+### 2.3 Prompt Template — Copy, Fill In, Paste to Agent
 
-> Here is the issue: `<LINK TO GITHUB ISSUE>`
-> Here is the agent guide: `docs/agents.md`
->
-> Please read the guide first, then implement the fix, and iterate through **every CI step**
-> (lint → circ-deps → build → unit tests → e2e tests) until all pass.
-> Only then commit and push to the branch `ufal/<branch-name>`.
-> If e2e tests fail on known pre-existing issues, that is acceptable — see the guide.
+```
+Here is the GitHub issue to fix: <PASTE ISSUE URL>
 
-That's it. The rest is the agent's job.
+Read the agent guide at docs/agents.md first.
 
----
+Environment info:
+- Backend services (REST API, Solr, PostgreSQL) are running in Docker on default ports
+- Frontend will run locally (you start it with yarn start:dev or yarn serve:ssr)
+- Admin credentials if necessary for the issue: <PASTE EMAIL>/<PASTE PASSWORD>
 
-## 3. The CI Pipeline (`build.yml`)
+Please:
+1. Read the issue and understand the problem
+2. Use Playwright MCP to navigate to the affected page and visually confirm the bug
+3. Investigate the codebase to find the root cause
+4. Implement a fix
+5. Use Playwright MCP again to verify the fix is working
+6. Run all CI checks (lint → circ-deps → build → unit tests) and iterate until all pass
+7. Only commit and push when everything is green
 
-Every PR triggers CI on Node 18.x and 20.x. **All steps must pass.**
+If the issue involves a specific page, here is the direct URL: <OPTIONAL URL>
+```
 
-| # | Step | Command | Time |
-|---|------|---------|------|
-| 1 | Install | `yarn install --frozen-lockfile` | ~2 min |
-| 2 | Lint | `yarn run lint --quiet` | ~76 sec |
-| 3 | Circular deps | `yarn run check-circ-deps` | ~34 sec |
-| 4 | Build (browser + server) | `yarn run build:prod` | ~6.5 min |
-| 5 | Unit tests | `yarn run test:headless` | ~3.5 min |
-| 6 | Docker backend up | `docker compose -f docker/docker-compose-ci.yml up -d` + assetstore | ~3 min |
-| 7 | E2E tests | `yarn run serve:ssr` + Cypress via `cypress-io/github-action` | ~5 min |
-| 8 | SSR verification | `wget` + `grep` on 10 entity pages (Home, Community, Collection, Publication, Person, Project, OrgUnit, Journal, Journal Volume, Journal Issue) | ~1 min |
-| 9 | HTTP status codes | 301 `/handle/*`, 403, 404, 500 | ~30 sec |
+That's it. Everything below is the agent's responsibility.
 
 ---
 
-## 4. Agent Workflow — Step-by-Step Iteration
+## 3. Agent Workflow
 
-### ⚠️ RULE: Do NOT commit or push until steps 1–5 all pass. Steps 6–7 if Docker backend is available.
+### 3.1 The Loop: Investigate → Fix → Verify → CI
 
 ```
-FOR EACH step below:
-  1. Run the command
-  2. If it FAILS → fix the code → rerun THAT SAME step
-  3. Only proceed to the next step when current one is green
+1. READ the issue — understand what's broken and where
+2. DETECT with Playwright MCP — navigate to the affected page, take snapshots,
+   confirm the bug visually (duplicate IDs, broken layout, wrong behavior, etc.)
+3. SEARCH the codebase — find the root cause in the source files
+4. IMPLEMENT the fix — minimal, focused changes
+5. VERIFY with Playwright MCP — navigate to the same page, confirm the fix works
+6. RUN CI checks in order — fix any failures, re-verify after each code change
+7. COMMIT & PUSH — only when everything passes
 ```
 
-### Step 1 — Install Dependencies
-```bash
-yarn install --frozen-lockfile
-```
+### 3.2 CI Pipeline — Run In This Order
 
-### Step 2 — Lint
-```bash
-yarn run lint --quiet
-```
-Must exit with code 0 and print "All files pass linting."
+Every step must pass before proceeding to the next.
+
+| # | Step | Command | Time | Pass Criteria |
+|---|------|---------|------|---------------|
+| 1 | Lint | `yarn run lint --quiet` | ~76s | Exit 0, "All files pass linting." |
+| 2 | Circular deps | `yarn run check-circ-deps` | ~34s | "No circular dependency found!" |
+| 3 | Build | `yarn run build:prod` | ~6.5min | Two bundles (browser + server), no `Error:` lines |
+| 4 | Unit tests | `yarn run test:headless` | ~3.5min | ~5300 specs, 0 failures |
+| 5 | E2E tests | See §3.5 | ~5min | No new failures vs. `dtq-dev` baseline |
+
+**If any step fails**: fix the code → rerun **that same step** → only proceed when green.
+
+### 3.3 Running a Single Unit Test
 
-### Step 3 — Circular Dependencies
 ```bash
-yarn run check-circ-deps
+yarn run test:headless --include='**/path/to/component.spec.ts'
 ```
-Must print "✔ No circular dependency found!"
 
-**⚠️ PowerShell trap**: The underlying `madge --exclude` regex contains `|` pipe characters. PowerShell interprets `|` as a pipeline operator even inside quotes. Use the stop-parsing token:
+### 3.4 PowerShell Trap — Circular Dependency Check
+
+The `check-circ-deps` script uses `madge --exclude` with regex containing `|`. PowerShell interprets `|` as a pipeline operator. Use the stop-parsing token:
+
 ```powershell
 npx --% madge --exclude "(bitstream|bundle|collection|config-submission-form|eperson|item|version)\.model\.ts$" --circular --extensions ts ./
 ```
 
-### Step 4 — Production Build
+### 3.5 E2E Tests (Requires Docker Backend)
+
+Start the SSR server:
 ```bash
 yarn run build:prod
+yarn run serve:ssr &
+# Wait for http://localhost:4000 to respond
 ```
-Takes ~6.5 min. Run as a background process and poll for completion.
-Must produce **two** successful bundles: browser + server. Ignore warnings about unused theme components and CommonJS dependencies — these are pre-existing.
 
-### Step 5 — Unit Tests
+Run public-page specs (always safe, no login needed):
 ```bash
-yarn run test:headless
+npx cypress run --spec "cypress/e2e/footer.cy.ts,cypress/e2e/header.cy.ts,cypress/e2e/pagenotfound.cy.ts,cypress/e2e/browse-by-title.cy.ts,cypress/e2e/browse-by-author.cy.ts,cypress/e2e/browse-by-subject.cy.ts,cypress/e2e/community-list.cy.ts,cypress/e2e/search-page.cy.ts" --browser chrome
 ```
-Expect ~5 300 specs, 0 failures. If a test fails, read the error, fix the code or test, rerun.
 
-Run a single test file:
-```bash
-yarn run test:headless --include='**/path/to/component.spec.ts'
+On PowerShell, set the base URL first:
+```powershell
+$env:CYPRESS_BASE_URL="http://localhost:4000"
 ```
 
-### Step 6 — E2E Tests (requires Docker backend)
+### 3.6 E2E Test Categories
+
+| Category | Spec files | Requires |
+|----------|-----------|----------|
+| **Public pages** (always safe) | `footer`, `header`, `pagenotfound`, `browse-by-*`, `community-list`, `search-page`, `feedback` | Frontend only |
+| **Data-dependent** | `collection-page`, `community-page`, `item-page` | Backend + Demo Entities assetstore |
+| **Login-required** | `submission*`, `admin-*`, `my-dspace`, `profile-page`, `handle-page`, `health-page` | Backend + Demo Entities + valid credentials |
+
+### 3.7 Commit & Push
 
-Start the SSR server first (if not already running):
 ```bash
-yarn run serve:ssr &          # background
-# Wait for http://localhost:4000 to respond
+git add <changed-files>
+# NEVER commit: config/config.yml, .env.* files, coverage/, cypress/videos/
+git commit -m "fix: <concise description>"
+git push origin ufal/<branch-name>
 ```
 
-Run safe public-page specs (no login, no specific test data required):
-```bash
-npx cypress run --spec "cypress/e2e/footer.cy.ts,cypress/e2e/header.cy.ts,cypress/e2e/pagenotfound.cy.ts,cypress/e2e/browse-by-title.cy.ts,cypress/e2e/browse-by-author.cy.ts,cypress/e2e/browse-by-subject.cy.ts,cypress/e2e/community-list.cy.ts,cypress/e2e/search-page.cy.ts,cypress/e2e/feedback.cy.ts,cypress/e2e/browse-by-dateissued.cy.ts" --browser chrome
+---
+
+## 4. Using Playwright MCP for Detection & Verification
+
+Playwright MCP is the agent's **eyes**. Use it to **see** the problem and **confirm** the fix.
+
+### 4.1 Navigating to a Page
+
+```
+browser_navigate → http://localhost:4000/path/to/page
+browser_snapshot → get the accessibility tree of the page
 ```
 
-On Windows PowerShell, set the base URL first:
-```powershell
-$env:CYPRESS_BASE_URL="http://localhost:4000"
-npx cypress run --spec "cypress/e2e/footer.cy.ts,..." --browser chrome
+### 4.2 Running JavaScript on the Page
+
+Use `browser_evaluate` to inspect the DOM. Examples:
+
+**Check for duplicate HTML IDs**:
+```javascript
+async (page) => {
+  return await page.evaluate(() => {
+    const ids = [...document.querySelectorAll('[id]')].map(el => el.id).filter(Boolean);
+    const counts = {};
+    ids.forEach(id => { counts[id] = (counts[id] || 0) + 1; });
+    const dupes = Object.entries(counts).filter(([_, c]) => c > 1);
+    return { total: ids.length, unique: new Set(ids).size, duplicates: dupes };
+  });
+}
 ```
 
-### Step 7 — Commit & Push (only after all green)
+**Verify specific selectors still work** (backward compatibility):
+```javascript
+async (page) => {
+  return await page.evaluate(() => {
+    const selectors = ['input#dc_title', 'label[for=dc_title]', '.some-class'];
+    return selectors.map(s => `${s}: ${document.querySelectorAll(s).length}`);
+  });
+}
+```
 
-```bash
-git add <files>                 # NEVER add config/config.yml or .env.* files
-git commit -m "fix: <description>"
-git push origin ufal/<branch-name>
+**Check console errors**:
+```javascript
+async (page) => {
+  const errors = [];
+  page.on('console', msg => { if (msg.type() === 'error') errors.push(msg.text()); });
+  await page.reload();
+  await page.waitForTimeout(3000);
+  return errors;
+}
 ```
 
----
+### 4.3 Logging In (When Needed)
 
-## 5. E2E Test Categories & What to Run
+Some pages require authentication (submission forms, admin panels).
+Test credentials are defined in `cypress.config.ts` (look for `DSPACE_TEST_ADMIN_USER` / `DSPACE_TEST_ADMIN_PASSWORD`).
 
-| Category | Spec files | Requires |
-|----------|-----------|----------|
-| **Public pages** (always safe) | `footer`, `header`, `pagenotfound`, `browse-by-*`, `community-list`, `search-page`, `feedback` | Frontend only |
-| **Data-dependent** | `collection-page`, `community-page`, `item-page` | Backend + Demo Entities assetstore |
-| **Login-required** | `submission*`, `admin-*`, `my-dspace`, `profile-page`, `handle-page`, `health-page`, `tombstone`, `system-wide-alert` | Backend + Demo Entities + valid credentials |
-| **No active tests** | `homepage`, `homepage-statistics`, `search-navbar`, `login-modal` | N/A |
+1. Navigate to the login page
+2. Dismiss the DiscoJuice/Shibboleth overlay if it appears:
+   ```javascript
+   await page.evaluate(() => {
+     document.querySelectorAll('[class*="discojuice"]').forEach(el => el.remove());
+   });
+   ```
+3. Fill in credentials and submit the login form
+4. Navigate to the target page
 
-### Cypress Config
+### 4.4 Screenshots for Evidence
 
-- Config: `cypress.config.ts`
-- Specs: `cypress/e2e/*.cy.ts`
-- Default base URL: `http://localhost:4000` (override with `CYPRESS_BASE_URL`)
-- Retries: 2 in run mode, 0 in open mode
-- Test data: [Demo Entities Data set](https://github.com/DSpace-Labs/AIP-Files/releases/tag/demo-entities-data)
+Use `browser_take_screenshot` before and after the fix to document the change.
 
-### Key Test Variables (from `cypress.config.ts`)
+### 4.5 Dev Server vs. SSR Mode
 
-| Variable | Value |
-|----------|-------|
-| `DSPACE_TEST_ADMIN_USER` | `dspacedemo+admin@gmail.com` |
-| `DSPACE_TEST_ADMIN_PASSWORD` | `dspace` |
-| `DSPACE_TEST_COMMUNITY` | `0958c910-2037-42a9-81c7-dca80e3892b4` |
-| `DSPACE_TEST_COLLECTION` | `282164f5-d325-4740-8dd1-fa4d6d3e7200` |
-| `DSPACE_TEST_ENTITY_PUBLICATION` | `6160810f-1e53-40db-81ef-f6621a727398` |
+| Mode | Command | CORS | Hot Reload |
+|------|---------|------|------------|
+| Dev server | `yarn start:dev` | ⚠️ Must match backend's `dspace.ui.url` port | ✅ Yes |
+| SSR mode | `yarn build:prod` → `yarn serve:ssr` | ✅ No issues (server-side proxy) | ❌ No |
+
+**Prefer SSR mode** for Playwright verification. It avoids CORS issues and reflects the real production behavior. Use dev server only when you need rapid iteration.
 
 ---
 
-## 6. Known Pre-existing E2E Failures (Not Your Bug)
+## 5. Known Pre-Existing E2E Failures
 
-Before panicking about a red test, check this list:
+Before panicking about a red test, check if it was already failing on `dtq-dev`:
 
-| Symptom | Affected Specs | Root Cause | Action |
-|---------|---------------|------------|--------|
-| `cy.get('.discojuice_close').click()` fails — element is `display: none` | All login-dependent tests | DiscoJuice popup is hidden in Docker env | **Skip** — pre-existing |
-| `cy.wait('@viewevent')` timeout | `collection-page.cy.ts` | Matomo/statistics not configured in Docker | **Skip** — pre-existing |
-| Entity redirect fails | `item-page.cy.ts` | Backend entity routing not configured | **Skip** — pre-existing |
-| `link-in-text-block` a11y violation | `privacy.cy.ts`, `end-user-agreement.cy.ts` | CSS link styling issue | **Skip** — pre-existing |
+| Symptom | Affected Specs | Cause |
+|---------|---------------|-------|
+| DiscoJuice `display: none` click fails | Login-dependent tests | Docker env popup issue |
+| `cy.wait('@viewevent')` timeout | `collection-page.cy.ts` | Matomo not configured |
+| Entity redirect fails | `item-page.cy.ts` | Backend routing issue |
+| `link-in-text-block` a11y violation | `privacy.cy.ts`, `end-user-agreement.cy.ts` | CSS styling issue |
 
 **Rule**: Only fix failures that YOUR changes caused. If a test was already failing on `dtq-dev`, leave it alone.
 
 ---
 
-## 7. Hard-Won Lessons (Pitfalls & Traps)
+## 6. Pitfalls & Lessons Learned
 
 These come from real agent sessions. Read them before writing code.
 
-### 7.1 Angular Template Binding
+### 6.1 Angular Template Binding
 
-❌ **WRONG** — interpolation inside `aria-*` / `attr.*`:
 ```html
-<div aria-labelledby="prefix-{{ variable }}">
-```
-Angular will throw `Can't bind to 'aria-labelledby' since it isn't a known property` at build time.
+<!-- ❌ WRONG — interpolation in non-standard attributes -->
+<div aria-labelledby="prefix-{{ var }}">
 
-✅ **CORRECT** — property binding:
-```html
-<div [attr.aria-labelledby]="'prefix-' + variable">
+<!-- ✅ CORRECT — property binding -->
+<div [attr.aria-labelledby]="'prefix-' + var">
 ```
 
-This applies to **all** `aria-*` and custom HTML attributes. Always use `[attr.X]="expression"` instead of `X="{{ interpolation }}"` for non-standard attributes.
+This applies to all `aria-*` and custom HTML attributes. Always use `[attr.X]="expression"` instead of `X="{{ interpolation }}"`.
 
-### 7.2 Dynamic HTML IDs Must Be Valid
-
-HTML `id` attributes must not contain whitespace or special characters. If an ID is built from dynamic data (e.g., bundle names, file names, user input), **sanitize it**:
+### 6.2 Dynamic HTML IDs Must Be Valid
 
+HTML `id` attributes must not contain whitespace or special characters. Sanitize dynamic data:
 ```typescript
 sanitizedName = rawName.replace(/\s+/g, '');
 ```
 
-Then use `sanitizedName` in the template `id` attribute. Never trust that a service will return a "safe" string for an HTML ID.
-
-### 7.3 Conditional `aria-describedby`
-
-If a `<label>` or description element is conditionally rendered (`*ngIf`), the `aria-describedby` pointing to it must also be conditional:
+### 6.3 Conditional `aria-describedby`
 
+If a description element is conditionally rendered (`*ngIf`), the `aria-describedby` pointing to it must also be conditional:
 ```html
-<!-- The label only exists when `label` is truthy -->
 <span *ngIf="label" [id]="'desc-' + uniqueId">{{ label }}</span>
-
-<!-- So aria-describedby must be conditional too -->
 <input [attr.aria-describedby]="label ? 'desc-' + uniqueId : null">
 ```
 
-If you always set `aria-describedby` to a non-existent element, screen readers will be confused and accessibility audits (Cypress axe-core) may flag it.
+### 6.4 Never Change Form Element IDs Unless You Have To
 
-### 7.4 Never Change Form Element IDs Unless You Have To
+Submission forms use IDs like `input#dc_title`, `label[for=local_hasCMDI]` etc. These are referenced by Cypress e2e selectors and `formModel` definitions. Changing them cascades into dozens of broken tests. Unless the issue specifically requires it, leave form IDs alone.
 
-Submission forms use IDs like `input#dc_title`, `label[for=local_hasCMDI]` etc. These are referenced by:
-- Cypress e2e selectors in `cypress/e2e/submission*.cy.ts`
-- `formModel` definitions in `src/app/shared/form/builder/`
-- DynamicFormControlLayout configs
+### 6.5 `aria-labelledby` Must Match Label IDs
 
-If you change these IDs (e.g., adding suffixes for uniqueness), **every Cypress selector breaks**. Unless the issue specifically requires changing form IDs, leave them alone.
+Many child form components reference `'label_' + model.id` in `[attr.aria-labelledby]`. If you change a label's `[id]`, you break accessibility wiring in 13+ template files. Keep label IDs stable — if deduplicating, change the form control ID, not the label.
 
-### 7.5 PowerShell-Specific Issues
+### 6.6 Static State Leaks Between Tests
 
-| Issue | Solution |
-|-------|---------|
-| `yarn run check-circ-deps` fails with pipe error | Use `npx --%` stop-parsing token (see Step 3 above) |
-| Environment variables don't persist across commands | Set them on the same line or use `$env:VAR='val'` before each command |
-| `&&` is not valid in PowerShell 5.1 | Use `;` to chain commands |
+This project uses `{ teardown: { destroyAfterEach: false } }` (see `src/test.ts`), so `ngOnDestroy` does NOT run between unit tests. Any static registry or singleton must be explicitly cleared in the global `afterEach` in `src/test.ts`, or it will leak state across specs.
 
-### 7.6 Build Output — What to Ignore vs. What Matters
+### 6.7 When to Revert Your Approach
 
-**Ignore** (pre-existing, harmless):
-- `Warning: X.component.ts is part of the TypeScript compilation but it's unused`
-- `Warning: CommonJS or AMD dependencies can cause optimization bailouts`
-- `Warning: bundle initial exceeded maximum budget`
-- `Warning: Expected identifier but found "*"` (CSS hack for old IE)
+If your change causes dozens of cascading test failures, **stop and rethink**. It's cheaper to revert the whole approach than to chase 50 broken selectors. A minimal, targeted fix is always better than a sweeping refactor.
 
-**Do NOT ignore** (real errors):
-- `Error: ...` lines in the build output
-- `Template parse errors`
-- `Property 'X' does not exist on type 'Y'`
-- `Module not found`
+### 6.8 PowerShell-Specific Issues
 
-### 7.7 Files You Must NEVER Commit
+| Issue | Solution |
+|-------|---------|
+| `check-circ-deps` fails with pipe error | Use `npx --%` stop-parsing token |
+| `&&` not valid in PowerShell 5.1 | Use `;` to chain commands |
+| Env vars don't persist | Use `$env:VAR='val'` before each command |
 
-| File | Reason |
-|------|--------|
-| `.env.*` files | Local environment configs |
-| `cypress/videos/`, `cypress/screenshots/` | Test artifacts |
-| `coverage/` | Generated coverage reports |
+### 6.9 Build Warnings to Ignore
 
-### 7.8 Reverting a Bad Approach
+These are pre-existing and harmless:
+- `Warning: X.component.ts is unused` (theme components)
+- `Warning: CommonJS or AMD dependencies`
+- `Warning: bundle exceeded maximum budget`
 
-If your change looks correct but breaks dozens of tests, **stop and reconsider**. It's cheaper to revert a whole approach than to chase 50 cascading failures. Example: Adding unique ID suffixes to dynamic form elements broke all Cypress `input#dc_*` selectors — the right move was to revert the form changes entirely and fix only the static duplicates.
+Real errors always start with `Error:`.
 
-### 7.9 Unit Test Spec Selectors
+### 6.10 SSR Compatibility
 
-When changing an `id`, `class`, or tag in a template, **always check the corresponding `.spec.ts` file**:
-```bash
-# Find the spec for a component
-ls src/app/.../my-component.component.spec.ts
+All code must work with Angular Universal. Never use `document` or `window` directly:
+```typescript
+import { isPlatformBrowser } from '@angular/common';
+if (isPlatformBrowser(this.platformId)) {
+  // browser-only code
+}
+```
 
-# Search for selectors that reference the changed ID/class
+### 6.11 Always Check `.spec.ts` When Changing Templates
+
+When changing an `id`, `class`, or tag in a template, check the corresponding `.spec.ts`:
+```bash
 grep -n "By.css" src/app/.../my-component.component.spec.ts
 ```
-If a test uses `By.css('[id^="oldPrefix"]')` and you removed that ID, update the selector or the test will fail.
+If a test uses a selector you changed, update it or the test will fail.
+
+---
+
+## 7. Example: Duplicate HTML IDs in ng-dynamic-forms
+
+> This section documents a real fix for reference. The patterns here apply to similar problems.
+
+**Problem**: The submission edit page renders dynamic form fields via `@ng-dynamic-forms`. When the same metadata field appears in multiple `DynamicRowGroupModel` groups, each instance gets the **same HTML ID**, producing duplicates.
+
+**Root cause**: `@ng-dynamic-forms/core` `getElementId(model)` only handles `DynamicFormArrayGroupModel` parents. It does NOT handle `DynamicFormGroupModel` / `DynamicRowGroupModel` parents, even though they have unique auto-generated IDs.
+
+**Solution**: A `UniqueIdRegistry` static class that:
+1. First occurrence of a base ID → returns the original ID (preserves Cypress selectors)
+2. Subsequent occurrences → appends `_1`, `_2`, etc. via a monotonic counter
+3. Components call `register()` on init and `release()` on destroy
+
+The `get id()` override was added to `DsDynamicFormControlContainerComponent` and `DsDynamicScrollableDropdownComponent`.
+
+**Also fixed**: `id="license_option_{{ license.id }}"` → `[id]="'license_option_' + license.id"` (interpolation rendered empty because Angular consumed it before DOM render).
 
 ---
 
-## 8. Docker Reference
+## 8. Docker Reference (Backend Services Only)
+
+Docker runs only the backend services. The Angular frontend always runs locally.
 
-### Compose Files (`docker/`)
+### Compose Files
 
 | File | Purpose |
-|------|---------|
-| `docker-compose-ci.yml` | CI backend (DSpace REST + PostgreSQL + Solr) |
-| `docker-compose.yml` | Full stack dev |
+|------|--------|
+| `docker-compose-ci.yml` | Backend stack for CI/testing (DSpace REST + PostgreSQL + Solr) |
+| `docker-compose.yml` | Full stack dev (includes a frontend container — but we run frontend locally instead) |
 | `docker-compose-rest.yml` | REST backend only |
-| `cli.yml` | DSpace CLI commands |
-| `cli.assetstore.yml` | Load Demo Entities test data |
+| `cli.yml` + `cli.assetstore.yml` | Load Demo Entities test data |
+
+### Default Ports
+
+| Service | Port | Where |
+|---------|------|-------|
+| DSpace REST API | 8080 | Docker |
+| PostgreSQL | 5432 | Docker |
+| Solr | 8983 | Docker |
+| Angular Frontend | 4000 | **Local** (not Docker) |
 
-### Default CI Ports
+### Test Variables
 
-| Service | Port |
-|---------|------|
-| DSpace REST API | 8080 |
-| PostgreSQL | 5432 |
-| Solr | 8983 |
-| Angular Frontend (SSR) | 4000 |
+Test credentials and UUIDs for e2e tests are defined in `cypress.config.ts` under the `env` section. Look for `DSPACE_TEST_ADMIN_USER`, `DSPACE_TEST_ADMIN_PASSWORD`, `DSPACE_TEST_COMMUNITY`, etc. These are standard DSpace demo-instance values — do **not** replace them with real credentials.
+
+### Connecting the Local Frontend to Docker Backend
+
+The backend's `dspace.ui.url` determines CORS allowed origins. Your local dev server port **must match** this URL, or browser XHR requests will be blocked.
+
+1. Check which UI port the backend expects (look at the Docker compose env vars for `dspace.ui.url`)
+2. Edit `config/config.yml` temporarily to match those ports
+3. Run: `yarn start:dev`
+4. **Never commit** `config/config.yml` changes — add it to your local `.gitignore` or always `git checkout` before committing
+
+Alternatively, use SSR mode (`yarn build:prod` → `yarn serve:ssr`) which proxies API calls server-side and avoids CORS entirely. This is the **recommended approach** for Playwright verification.
 
 ### Docker Commands
 
@@ -357,7 +422,6 @@ docker compose -p ci -f docker/docker-compose-ci.yml up -d
 docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
 
 # Verify
-docker container ls
 curl http://localhost:8080/server/api/core/sites
 
 # Stop
@@ -368,19 +432,18 @@ docker compose -p ci -f docker/docker-compose-ci.yml down
 
 ## 9. Common Errors & Solutions
 
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `The engine "node" is incompatible` | Node 20+ | `nvm use 18` |
-| `The Cypress App could not be downloaded` | Network | `CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile` |
-| Out of memory during build | Heap too small | `$env:NODE_OPTIONS='--max-old-space-size=4096'` |
-| Merge conflicts in `yarn.lock` | Branch diverged | `git checkout --theirs yarn.lock; yarn install; git add yarn.lock` |
-| `Can't bind to 'aria-labelledby'` | Template syntax | Use `[attr.aria-labelledby]="'...' + var"` not `aria-labelledby="...{{ var }}"` |
-| `Property 'X' does not exist on type` | Missing property | Add the property to the component class or fix the type |
-| Cypress can't connect | Frontend not running | Run `yarn run serve:ssr` first; check `CYPRESS_BASE_URL` |
-| `cy.wait()` timed out | Backend endpoint unavailable | Ensure Docker backend is up + assetstore loaded |
-| Docker images won't pull | Auth issue | `docker login ghcr.io` or check VPN/firewall |
-| `madge` pipe error on PowerShell | `|` in regex | Use `npx --%` stop-parsing token |
-| Test fails with `Cannot find element with id "..."` | You renamed/removed an ID | Update the test selector too |
+| Error | Fix |
+|-------|-----|
+| `The engine "node" is incompatible` | `nvm use 18` |
+| `Cypress App could not be downloaded` | `CYPRESS_INSTALL_BINARY=0 yarn install --frozen-lockfile` |
+| Out of memory during build | `$env:NODE_OPTIONS='--max-old-space-size=4096'` |
+| `yarn.lock` merge conflicts | `git checkout --theirs yarn.lock; yarn install; git add yarn.lock` |
+| `Can't bind to 'aria-labelledby'` | Use `[attr.aria-labelledby]="expr"` not interpolation |
+| Cypress can't connect | Run `yarn serve:ssr` first; check `CYPRESS_BASE_URL` |
+| CORS errors with dev server | Match port to backend's `dspace.ui.url`, or use SSR mode |
+| `madge` pipe error on PowerShell | Use `npx --%` stop-parsing token |
+| Test fails with `Cannot find element` | You renamed an ID — update the test selector too |
+| DiscoJuice overlay blocks login | `document.querySelector('.discojuice-overlay')?.remove()` |
 
 ---
 
@@ -388,47 +451,43 @@ docker compose -p ci -f docker/docker-compose-ci.yml down
 
 | Convention | Rule |
 |------------|------|
-| Component prefix | `ds-` (e.g., `<ds-navbar>`) |
-| File naming | `*.component.ts`, `*.service.ts`, `*.model.ts`, `*.spec.ts`, `*.module.ts` |
+| Component prefix | `ds-` |
 | Strings | Single quotes |
 | Indentation | 2 spaces |
-| Imports | Avoid barrel imports; import from specific files |
-| Lodash | Method imports: `import get from 'lodash/get'` |
-| SSR | All code must work with Angular Universal (no `document`/`window` without checks) |
-| Tests | Co-located with source (same directory, `.spec.ts` suffix) |
-| JSDoc | All new public methods and classes require TypeDoc comments |
+| Imports | Specific files, not barrels |
+| Lodash | `import get from 'lodash/get'` |
+| SSR | No raw `document`/`window` — use `isPlatformBrowser()` |
+| Tests | Co-located `.spec.ts` files |
+| JSDoc | Required on all new public methods |
 
 ---
 
 ## 11. Quick Reference
 
 ```bash
-# === Setup ===
+# Setup
 nvm use 18
 yarn install --frozen-lockfile
 
-# === Full CI validation (run in this order) ===
-yarn run lint --quiet              # ~76 sec
-yarn run check-circ-deps           # ~34 sec
-yarn run build:prod                # ~6.5 min
-yarn run test:headless             # ~3.5 min
+# CI validation (run in order)
+yarn run lint --quiet
+yarn run check-circ-deps
+yarn run build:prod
+yarn run test:headless
 
-# === Single unit test ===
+# Single test
 yarn run test:headless --include='**/path/to/test.spec.ts'
 
-# === Dev server (hot reload) ===
-yarn run start:dev                 # http://localhost:4000
+# Dev server
+yarn run start:dev
 
-# === E2E tests ===
-docker compose -p ci -f docker/docker-compose-ci.yml up -d
-docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
+# E2E
 yarn run build:prod
 yarn run serve:ssr &
-yarn run e2e                       # all specs
-# or specific:
 npx cypress run --spec "cypress/e2e/footer.cy.ts" --browser chrome
 
-# === Cleanup ===
+# Docker backend
+docker compose -p ci -f docker/docker-compose-ci.yml up -d
+docker compose -p ci -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli
 docker compose -p ci -f docker/docker-compose-ci.yml down
-yarn run clean:prod
 ```