+```
+
+- [ ] **Step 5: Write the SCSS**
+
+```scss
+.help-text {
+ display: flex;
+ gap: 8px;
+ align-items: flex-start;
+ padding: 9px 11px;
+ border-left: 3px solid var(--primary, #289694);
+ border-radius: 0 5px 5px 0;
+ background: var(--primary-light, #f5fcfc);
+ font-size: 12.5px;
+ line-height: 1.5;
+ color: var(--text-body, #7f868d);
+
+ .mat-icon {
+ flex: none;
+ font-size: 16px;
+ width: 16px;
+ height: 16px;
+ color: var(--primary, #289694);
+ }
+
+ &--warn {
+ border-left-color: var(--warning, #e2a01c);
+ background: rgba(226, 160, 28, 0.12);
+
+ .mat-icon {
+ color: var(--warning, #e2a01c);
+ }
+ }
+}
+```
+
+- [ ] **Step 6: Declare `HelpHintComponent` in `time-planning-pn.module.ts`**
+
+- [ ] **Step 7: Run the tests and confirm they pass**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: PASS.
+
+- [ ] **Step 8: Pre-commit gate** — code-reviewer and code-simplifier in parallel; resolve findings.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add eform-client/src/app/plugins/modules/time-planning-pn/help \
+ eform-client/src/app/plugins/modules/time-planning-pn/time-planning-pn.module.ts
+git commit -m "feat(help): add tp-help-hint inline hint component"
+```
+
+---
+
+### Task 7: HelpPanelService and tp-help-panel
+
+**Files:**
+- Create: `help/services/help-panel.service.ts`
+- Create: `help/components/help-panel/help-panel.component.ts`
+- Create: `help/components/help-panel/help-panel.component.html`
+- Create: `help/components/help-panel/help-panel.component.scss`
+- Modify: `time-planning-pn.module.ts`
+- Test: `help/services/help-panel.service.spec.ts`
+- Test: `help/components/help-panel/help-panel.component.spec.ts`
+
+**Interfaces:**
+- Consumes: `HelpContentService` (Task 2), `HelpSearchService` + `HelpSearchResult` (Task 4).
+- Produces: `HelpPanelService` with `isOpen$: Observable`, `target$: Observable`, `open(target?: HelpEntryId): void`, `close(): void`; and `HelpPanelComponent`, selector `tp-help-panel`, `@Input() isAdmin = false`, `@Output() replayTourRequested = new EventEmitter()`.
+- **Does not** consume `HelpTourService` — that service does not exist until Task 8. The panel raises `replayTourRequested` and Task 9 wires it to the tour.
+
+- [ ] **Step 1: Write the failing service test**
+
+```ts
+import { HelpPanelService } from './help-panel.service';
+import { firstValueFrom } from 'rxjs';
+
+describe('HelpPanelService', () => {
+ it('starts closed', async () => {
+ const service = new HelpPanelService();
+ expect(await firstValueFrom(service.isOpen$)).toBe(false);
+ });
+
+ it('opens with no target', async () => {
+ const service = new HelpPanelService();
+ service.open();
+ expect(await firstValueFrom(service.isOpen$)).toBe(true);
+ expect(await firstValueFrom(service.target$)).toBeNull();
+ });
+
+ it('opens on a target and clears it on close', async () => {
+ const service = new HelpPanelService();
+ service.open('flex.sumFlex');
+ expect(await firstValueFrom(service.target$)).toBe('flex.sumFlex');
+ service.close();
+ expect(await firstValueFrom(service.isOpen$)).toBe(false);
+ expect(await firstValueFrom(service.target$)).toBeNull();
+ });
+});
+```
+
+- [ ] **Step 2: Write the failing component test**
+
+```ts
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { FormsModule } from '@angular/forms';
+import { MatIconModule } from '@angular/material/icon';
+import { MatButtonModule } from '@angular/material/button';
+import { TranslateService } from '@ngx-translate/core';
+import { HelpPanelComponent } from './help-panel.component';
+import { HelpPanelService } from '../../services/help-panel.service';
+
+describe('HelpPanelComponent', () => {
+ let fixture: ComponentFixture;
+ let panel: HelpPanelService;
+
+ beforeEach(async () => {
+ await TestBed.configureTestingModule({
+ declarations: [HelpPanelComponent],
+ imports: [FormsModule, MatIconModule, MatButtonModule],
+ providers: [
+ HelpPanelService,
+ { provide: TranslateService, useValue: { currentLang: 'en-US' } },
+ ],
+ }).compileComponents();
+
+ fixture = TestBed.createComponent(HelpPanelComponent);
+ panel = TestBed.inject(HelpPanelService);
+ fixture.detectChanges();
+ });
+
+ it('renders nothing while closed', () => {
+ expect(fixture.nativeElement.querySelector('.tp-help-panel')).toBeNull();
+ });
+
+ it('browses grouped sections when open with no query', () => {
+ panel.open();
+ fixture.detectChanges();
+ expect(fixture.nativeElement.querySelector('.tp-help-panel')).not.toBeNull();
+ expect(fixture.componentInstance.isSearching).toBe(false);
+ expect(fixture.nativeElement.textContent).toContain('Date range');
+ });
+
+ it('switches to results when a query is typed', () => {
+ panel.open();
+ fixture.componentInstance.onQueryChange('vacation');
+ fixture.detectChanges();
+ expect(fixture.componentInstance.isSearching).toBe(true);
+ expect(fixture.componentInstance.results.length).toBeGreaterThan(0);
+ });
+
+ it('hides admin-only entries when isAdmin is false', () => {
+ fixture.componentInstance.isAdmin = false;
+ panel.open();
+ fixture.detectChanges();
+ const ids = fixture.componentInstance.sections
+ .flatMap(section => section.entries.map(entry => entry.id));
+ expect(ids).not.toContain('toolbar.payrollExport');
+ });
+
+ it('marks the deep-link target', () => {
+ panel.open('flex.sumFlex');
+ fixture.detectChanges();
+ expect(fixture.componentInstance.targetId).toBe('flex.sumFlex');
+ });
+
+ it('closes through the service', () => {
+ panel.open();
+ fixture.detectChanges();
+ fixture.componentInstance.close();
+ fixture.detectChanges();
+ expect(fixture.nativeElement.querySelector('.tp-help-panel')).toBeNull();
+ });
+});
+```
+
+- [ ] **Step 3: Run both and confirm they fail**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: FAIL — modules not found.
+
+- [ ] **Step 4: Implement `HelpPanelService`**
+
+```ts
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+import { HelpEntryId } from '../help.model';
+
+@Injectable({ providedIn: 'root' })
+export class HelpPanelService {
+ private readonly openState = new BehaviorSubject(false);
+ private readonly targetState = new BehaviorSubject(null);
+
+ readonly isOpen$: Observable = this.openState.asObservable();
+ readonly target$: Observable = this.targetState.asObservable();
+
+ open(target?: HelpEntryId): void {
+ this.targetState.next(target ?? null);
+ this.openState.next(true);
+ }
+
+ close(): void {
+ this.openState.next(false);
+ this.targetState.next(null);
+ }
+}
+```
+
+- [ ] **Step 5: Implement `HelpPanelComponent`**
+
+```ts
+import { Component, EventEmitter, Input, OnDestroy, OnInit, Output } from '@angular/core';
+import { Subscription } from 'rxjs';
+import { HelpEntry, HelpEntryId, HelpProse, HelpSection, HelpUiStrings } from '../../help.model';
+import { HelpContentService } from '../../services/help-content.service';
+import { HelpPanelService } from '../../services/help-panel.service';
+import { HelpSearchResult, HelpSearchService } from '../../services/help-search.service';
+
+interface PanelSection {
+ section: HelpSection;
+ entries: HelpEntry[];
+}
+
+const SECTION_ORDER: HelpSection[] = ['task', 'toolbar', 'grid', 'dayCell', 'flex'];
+
+@Component({
+ selector: 'tp-help-panel',
+ templateUrl: './help-panel.component.html',
+ styleUrls: ['./help-panel.component.scss'],
+ standalone: false,
+})
+export class HelpPanelComponent implements OnInit, OnDestroy {
+ @Input() isAdmin = false;
+
+ isOpen = false;
+ targetId: HelpEntryId | null = null;
+ query = '';
+ results: HelpSearchResult[] = [];
+ sections: PanelSection[] = [];
+ expanded: HelpEntryId | null = null;
+
+ private readonly subscriptions = new Subscription();
+
+ @Output() replayTourRequested = new EventEmitter();
+
+ constructor(
+ private helpContent: HelpContentService,
+ private helpSearch: HelpSearchService,
+ private helpPanel: HelpPanelService,
+ ) {}
+
+ get ui(): HelpUiStrings {
+ return this.helpContent.ui();
+ }
+
+ get isSearching(): boolean {
+ return this.query.trim().length > 0;
+ }
+
+ ngOnInit(): void {
+ this.subscriptions.add(this.helpPanel.isOpen$.subscribe(isOpen => {
+ this.isOpen = isOpen;
+ if (isOpen) {
+ this.buildSections();
+ } else {
+ this.query = '';
+ this.results = [];
+ }
+ }));
+ this.subscriptions.add(this.helpPanel.target$.subscribe(target => {
+ this.targetId = target;
+ this.expanded = target;
+ }));
+ }
+
+ ngOnDestroy(): void {
+ this.subscriptions.unsubscribe();
+ }
+
+ onQueryChange(query: string): void {
+ this.query = query;
+ this.results = this.helpSearch.search(query, { isAdmin: this.isAdmin });
+ }
+
+ clearQuery(): void {
+ this.onQueryChange('');
+ }
+
+ toggleEntry(id: HelpEntryId): void {
+ this.expanded = this.expanded === id ? null : id;
+ }
+
+ prose(id: HelpEntryId): HelpProse {
+ return this.helpContent.prose(id);
+ }
+
+ sectionLabel(section: HelpSection): string {
+ const labels: Record = {
+ task: this.ui.sectionTask,
+ toolbar: this.ui.sectionToolbar,
+ grid: this.ui.sectionGrid,
+ dayCell: this.ui.sectionDayCell,
+ flex: this.ui.sectionFlex,
+ };
+ return labels[section];
+ }
+
+ close(): void {
+ this.helpPanel.close();
+ }
+
+ /**
+ * Asks the host to replay the tour. The panel deliberately does not depend on
+ * HelpTourService — it is built before the tour exists, and keeping the panel
+ * independent of it means neither has to know about the other.
+ */
+ replayTour(): void {
+ this.helpPanel.close();
+ this.replayTourRequested.emit();
+ }
+
+ private buildSections(): void {
+ const entries = this.helpContent.entries({ isAdmin: this.isAdmin });
+ this.sections = SECTION_ORDER
+ .map(section => ({ section, entries: entries.filter(entry => entry.section === section) }))
+ .filter(group => group.entries.length > 0);
+ }
+}
+```
+
+- [ ] **Step 6: Write the template**
+
+```html
+
+```
+
+All chrome labels come from `HelpUiStrings` (Task 1), never the `translate` pipe — the plugin's 25 shared locale files stay untouched.
+
+- [ ] **Step 7: Write the SCSS**
+
+```scss
+.tp-help-panel {
+ position: fixed;
+ top: 0;
+ right: 0;
+ z-index: 900;
+ display: flex;
+ flex-direction: column;
+ width: 340px;
+ max-width: 100vw;
+ height: 100vh;
+ border-left: 1px solid var(--border, #e2e6e9);
+ background: var(--bg, #ffffff);
+ box-shadow: -8px 0 24px rgba(15, 19, 22, 0.08);
+
+ &__top {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 13px 15px;
+ border-bottom: 1px solid var(--border, #e2e6e9);
+
+ h5 {
+ margin: 0;
+ font-size: 14px;
+ font-weight: 600;
+ }
+ }
+
+ &__spacer { flex: 1; }
+
+ &__search {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ margin: 11px 15px;
+ padding: 8px 13px;
+ border: 1px solid var(--border, #e2e6e9);
+ border-radius: 19px;
+
+ input {
+ flex: 1;
+ border: 0;
+ background: none;
+ font-size: 13px;
+ color: var(--text-header, #0f1316);
+
+ &:focus { outline: none; }
+ }
+
+ button {
+ border: 0;
+ background: none;
+ cursor: pointer;
+ }
+ }
+
+ &__body {
+ flex: 1;
+ overflow-y: auto;
+ padding-bottom: 16px;
+ }
+
+ &__section {
+ margin: 14px 0 5px;
+ padding: 0 15px;
+ font-size: 10.5px;
+ font-weight: 500;
+ letter-spacing: 0.1em;
+ text-transform: uppercase;
+ color: var(--primary, #289694);
+ }
+
+ &__count {
+ margin: 10px 15px 2px;
+ font-size: 11px;
+ color: var(--text-body, #7f868d);
+ }
+}
+
+.tp-help-entry {
+ padding: 7px 15px 9px;
+ border-left: 2px solid transparent;
+
+ &--target {
+ border-left-color: var(--primary, #289694);
+ background: var(--primary-light, #f5fcfc);
+ }
+
+ &__head {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ width: 100%;
+ padding: 0;
+ border: 0;
+ background: none;
+ text-align: left;
+ cursor: pointer;
+
+ b {
+ font-size: 12.5px;
+ font-weight: 500;
+ color: var(--text-header, #0f1316);
+ }
+ }
+
+ &__kind {
+ flex: none;
+ padding: 0 4px;
+ border: 1px solid var(--border, #e2e6e9);
+ border-radius: 3px;
+ font-size: 9.5px;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--text-body, #7f868d);
+
+ &--task {
+ border-color: var(--primary, #289694);
+ color: var(--primary, #289694);
+ }
+ }
+
+ p {
+ margin: 2px 0 0;
+ font-size: 12px;
+ line-height: 1.5;
+ color: var(--text-body, #7f868d);
+ }
+
+ &__steps {
+ margin: 8px 0 0;
+ padding-left: 17px;
+
+ li {
+ margin-bottom: 3px;
+ font-size: 12px;
+ line-height: 1.5;
+ color: var(--text-header, #0f1316);
+ }
+ }
+}
+```
+
+- [ ] **Step 8: Declare `HelpPanelComponent` in `time-planning-pn.module.ts`** and ensure `FormsModule` is imported there.
+
+- [ ] **Step 9: Run the tests and confirm they pass**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: PASS.
+
+- [ ] **Step 10: Pre-commit gate** — code-reviewer and code-simplifier in parallel; resolve findings.
+
+- [ ] **Step 11: Commit**
+
+```bash
+git add eform-client/src/app/plugins/modules/time-planning-pn/help \
+ eform-client/src/app/plugins/modules/time-planning-pn/time-planning-pn.module.ts \
+ eform-client/src/app/plugins/modules/time-planning-pn/i18n
+git commit -m "feat(help): add searchable help side panel"
+```
+
+---
+
+### Task 8: HelpTourService and tp-help-tour
+
+**Files:**
+- Create: `help/services/help-tour.service.ts`
+- Create: `help/components/help-tour/help-tour.component.ts`
+- Create: `help/components/help-tour/help-tour.component.html`
+- Create: `help/components/help-tour/help-tour.component.scss`
+- Modify: `time-planning-pn.module.ts`
+- Test: `help/services/help-tour.service.spec.ts`
+- Test: `help/components/help-tour/help-tour.component.spec.ts`
+
+**Interfaces:**
+- Consumes: `HelpContentService.tourEntries` (Task 2).
+- Produces: `HelpTourService` with `state$: Observable`, `start(tour: HelpTourName, opts: { isAdmin: boolean }): void`, `next(): void`, `stop(): void`, `hasSeen(tour: HelpTourName): boolean`, `markSeen(tour: HelpTourName): void`; the exported interface `HelpTourState { entry: HelpEntry; index: number; total: number; }`; the storage key constant `TOUR_STORAGE_KEY = 'tp.planning.tour.v1'`; and `HelpTourComponent`, selector `tp-help-tour`.
+
+- [ ] **Step 1: Write the failing test**
+
+The tour must skip a step whose anchor is not in the DOM — that is the behaviour that keeps it working for a non-admin, and when the worker select is hidden because only one site exists.
+
+```ts
+import { TestBed } from '@angular/core/testing';
+import { TranslateService } from '@ngx-translate/core';
+import { firstValueFrom } from 'rxjs';
+import { HelpTourService, TOUR_STORAGE_KEY } from './help-tour.service';
+import { HelpContentService } from './help-content.service';
+
+describe('HelpTourService', () => {
+ let service: HelpTourService;
+
+ const anchor = (id: string) => {
+ const element = document.createElement('div');
+ element.setAttribute('data-tp-help', id);
+ document.body.appendChild(element);
+ };
+
+ beforeEach(() => {
+ document.body.innerHTML = '';
+ localStorage.clear();
+ TestBed.resetTestingModule();
+ TestBed.configureTestingModule({
+ providers: [
+ HelpTourService,
+ HelpContentService,
+ { provide: TranslateService, useValue: { currentLang: 'en-US' } },
+ ],
+ });
+ service = TestBed.inject(HelpTourService);
+ });
+
+ it('is idle before it starts', async () => {
+ expect(await firstValueFrom(service.state$)).toBeNull();
+ });
+
+ it('starts on the first step whose anchor exists', async () => {
+ anchor('grid.dayCellAnatomy');
+ service.start('page', { isAdmin: false });
+ const state = await firstValueFrom(service.state$);
+ expect(state?.entry.id).toBe('grid.dayCellAnatomy');
+ expect(state?.index).toBe(0);
+ expect(state?.total).toBe(1);
+ });
+
+ it('skips steps with no anchor in the DOM', async () => {
+ anchor('toolbar.dateRange');
+ anchor('grid.openDay');
+ service.start('page', { isAdmin: false });
+ let state = await firstValueFrom(service.state$);
+ expect(state?.entry.id).toBe('toolbar.dateRange');
+ expect(state?.total).toBe(2);
+ service.next();
+ state = await firstValueFrom(service.state$);
+ expect(state?.entry.id).toBe('grid.openDay');
+ });
+
+ it('never offers the payroll step to a non-admin even when its anchor exists', async () => {
+ anchor('toolbar.payrollExport');
+ anchor('toolbar.dateRange');
+ service.start('page', { isAdmin: false });
+ const state = await firstValueFrom(service.state$);
+ expect(state?.total).toBe(1);
+ expect(state?.entry.id).toBe('toolbar.dateRange');
+ });
+
+ it('ends after the last step', async () => {
+ anchor('toolbar.dateRange');
+ service.start('page', { isAdmin: false });
+ service.next();
+ expect(await firstValueFrom(service.state$)).toBeNull();
+ });
+
+ it('does not start when no anchor is present', async () => {
+ service.start('page', { isAdmin: false });
+ expect(await firstValueFrom(service.state$)).toBeNull();
+ });
+
+ it('does not mark a tour seen merely by being subscribed to', async () => {
+ // Regression guard: state$ replays null to every new subscriber.
+ await firstValueFrom(service.state$);
+ expect(service.hasSeen('page')).toBe(false);
+ });
+
+ it('marks the tour seen once it runs to the end', () => {
+ anchor('toolbar.dateRange');
+ service.start('page', { isAdmin: false });
+ expect(service.hasSeen('page')).toBe(false);
+ service.next();
+ expect(service.hasSeen('page')).toBe(true);
+ });
+
+ it('marks the tour seen when it is skipped', () => {
+ anchor('toolbar.dateRange');
+ service.start('page', { isAdmin: false });
+ service.stop();
+ expect(service.hasSeen('page')).toBe(true);
+ });
+
+ it('does not mark a tour seen when it could not start for lack of anchors', () => {
+ service.start('page', { isAdmin: false });
+ expect(service.hasSeen('page')).toBe(false);
+ });
+
+ it('records that a tour has been seen', () => {
+ expect(service.hasSeen('page')).toBe(false);
+ service.markSeen('page');
+ expect(service.hasSeen('page')).toBe(true);
+ expect(localStorage.getItem(TOUR_STORAGE_KEY)).toContain('page');
+ });
+
+ it('survives localStorage being unavailable', () => {
+ const getItem = jest.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+ throw new Error('blocked');
+ });
+ expect(service.hasSeen('page')).toBe(false);
+ getItem.mockRestore();
+ });
+});
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: FAIL — `Cannot find module './help-tour.service'`.
+
+- [ ] **Step 3: Implement `HelpTourService`**
+
+```ts
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+import { HelpEntry, HelpTourName } from '../help.model';
+import { HelpContentService } from './help-content.service';
+
+export const TOUR_STORAGE_KEY = 'tp.planning.tour.v1';
+
+export interface HelpTourState {
+ entry: HelpEntry;
+ index: number;
+ total: number;
+}
+
+@Injectable({ providedIn: 'root' })
+export class HelpTourService {
+ private readonly stateSubject = new BehaviorSubject(null);
+ private steps: HelpEntry[] = [];
+ private index = 0;
+ private current: HelpTourName | null = null;
+
+ readonly state$: Observable = this.stateSubject.asObservable();
+
+ constructor(private helpContent: HelpContentService) {}
+
+ /** Steps whose anchor is absent are dropped, never treated as an error. */
+ start(tour: HelpTourName, opts: { isAdmin: boolean }): void {
+ this.current = tour;
+ this.steps = this.helpContent
+ .tourEntries(tour, opts)
+ .filter(entry => !!this.anchorElement(entry));
+ this.index = 0;
+ this.emit();
+ }
+
+ next(): void {
+ this.index += 1;
+ this.emit();
+ }
+
+ /** Skipping counts as having seen it — but only if a step was actually shown. */
+ stop(): void {
+ if (this.current && this.steps.length > 0) {
+ this.markSeen(this.current);
+ }
+ this.current = null;
+ this.steps = [];
+ this.index = 0;
+ this.stateSubject.next(null);
+ }
+
+ /** True while a tour is on screen. */
+ get isRunning(): boolean {
+ return this.stateSubject.value !== null;
+ }
+
+ anchorElement(entry: HelpEntry): HTMLElement | null {
+ return entry.anchor
+ ? document.querySelector(`[data-tp-help="${entry.anchor}"]`)
+ : null;
+ }
+
+ hasSeen(tour: HelpTourName): boolean {
+ return this.readSeen().includes(tour);
+ }
+
+ markSeen(tour: HelpTourName): void {
+ const seen = this.readSeen();
+ if (!seen.includes(tour)) {
+ this.writeSeen([...seen, tour]);
+ }
+ }
+
+ private emit(): void {
+ const entry = this.steps[this.index];
+ if (entry) {
+ this.stateSubject.next({ entry, index: this.index, total: this.steps.length });
+ return;
+ }
+ // Ran to the end. Record it here, in the service, rather than in the component:
+ // state$ is a BehaviorSubject seeded null, so a component that marks "seen"
+ // whenever it observes null would do so on its very first subscription — before
+ // any tour has run — and the automatic first-run tour would never appear.
+ // `steps.length` guards the other direction: a tour that could not start because
+ // none of its anchors were in the DOM has not been seen, and must be offered again.
+ if (this.current && this.steps.length > 0) {
+ this.markSeen(this.current);
+ }
+ this.current = null;
+ this.stateSubject.next(null);
+ }
+
+ private readSeen(): string[] {
+ try {
+ return JSON.parse(localStorage.getItem(TOUR_STORAGE_KEY) ?? '[]') as string[];
+ } catch {
+ return [];
+ }
+ }
+
+ private writeSeen(seen: string[]): void {
+ try {
+ localStorage.setItem(TOUR_STORAGE_KEY, JSON.stringify(seen));
+ } catch {
+ // Storage unavailable (private mode, blocked cookies) — the tour simply reruns.
+ }
+ }
+}
+```
+
+- [ ] **Step 4: Implement `HelpTourComponent`**
+
+```ts
+import { Component, Input, OnDestroy, OnInit } from '@angular/core';
+import { ConnectedPosition } from '@angular/cdk/overlay';
+import { Subscription } from 'rxjs';
+import { HelpProse, HelpTourName } from '../../help.model';
+import { HelpContentService } from '../../services/help-content.service';
+import { HelpTourService, HelpTourState } from '../../services/help-tour.service';
+
+@Component({
+ selector: 'tp-help-tour',
+ templateUrl: './help-tour.component.html',
+ styleUrls: ['./help-tour.component.scss'],
+ standalone: false,
+})
+export class HelpTourComponent implements OnInit, OnDestroy {
+ @Input() tour: HelpTourName = 'page';
+ @Input() isAdmin = false;
+
+ state: HelpTourState | null = null;
+ origin: HTMLElement | null = null;
+
+ readonly positions: ConnectedPosition[] = [
+ { originX: 'center', originY: 'bottom', overlayX: 'start', overlayY: 'top', offsetY: 10 },
+ { originX: 'center', originY: 'top', overlayX: 'start', overlayY: 'bottom', offsetY: -10 },
+ ];
+
+ private readonly subscriptions = new Subscription();
+
+ constructor(
+ private helpContent: HelpContentService,
+ private helpTour: HelpTourService,
+ ) {}
+
+ get prose(): HelpProse | null {
+ return this.state ? this.helpContent.prose(this.state.entry.id) : null;
+ }
+
+ ngOnInit(): void {
+ // Deliberately does NOT mark the tour seen here. state$ is a BehaviorSubject
+ // seeded null, so this fires once at mount with state === null; marking seen
+ // there would suppress the automatic first run. The service records it instead,
+ // when a tour actually ends or is skipped.
+ this.subscriptions.add(this.helpTour.state$.subscribe(state => {
+ this.state = state;
+ this.origin = state ? this.helpTour.anchorElement(state.entry) : null;
+ }));
+ }
+
+ ngOnDestroy(): void {
+ this.subscriptions.unsubscribe();
+ }
+
+ next(): void {
+ this.helpTour.next();
+ }
+
+ skip(): void {
+ this.helpTour.stop();
+ }
+}
+```
+
+- [ ] **Step 5: Write the template**
+
+```html
+
+
+
+ {{ (state!.index + 1) }} / {{ state!.total }}
+
+
{{ tourProse.title }}
+
{{ tourProse.short }}
+
+
+
+
+
+
+```
+
+Labels come from `HelpUiStrings`; add `get ui(): HelpUiStrings { return this.helpContent.ui(); }` to `HelpTourComponent`. No key is added to the plugin's shared locale files.
+
+- [ ] **Step 6: Write the SCSS**
+
+```scss
+.tp-help-tour {
+ width: 320px;
+ padding: 15px 16px 13px;
+ border: 1px solid var(--border, #e2e6e9);
+ border-radius: 9px;
+ background: var(--bg, #ffffff);
+ box-shadow: 0 2px 6px rgba(15, 19, 22, 0.1), 0 12px 32px rgba(15, 19, 22, 0.16);
+
+ h5 {
+ margin: 0 0 6px;
+ font-size: 14px;
+ font-weight: 600;
+ }
+
+ &__step {
+ margin: 0 0 7px;
+ font-size: 10.5px;
+ letter-spacing: 0.1em;
+ text-transform: uppercase;
+ color: var(--primary, #289694);
+ }
+
+ &__body {
+ margin: 0 0 13px;
+ font-size: 12.5px;
+ line-height: 1.5;
+ color: var(--text-body, #7f868d);
+ }
+
+ &__actions {
+ display: flex;
+ gap: 9px;
+ align-items: center;
+ }
+
+ &__skip,
+ &__next {
+ padding: 7px 15px;
+ border: 1px solid var(--primary, #289694);
+ border-radius: 18px;
+ font-size: 12.5px;
+ font-weight: 500;
+ cursor: pointer;
+ }
+
+ &__skip {
+ background: transparent;
+ color: var(--primary, #289694);
+ }
+
+ &__next {
+ background: var(--primary, #289694);
+ color: #ffffff;
+ }
+}
+```
+
+- [ ] **Step 6b: Write the component regression spec**
+
+The bug this guards against is subtle and silent: a component that marks the tour seen
+whenever it observes a null state does so at mount, because `state$` is a
+`BehaviorSubject` seeded null — and the automatic first run then never happens.
+
+```ts
+import { TestBed } from '@angular/core/testing';
+import { OverlayModule } from '@angular/cdk/overlay';
+import { TranslateService } from '@ngx-translate/core';
+import { HelpTourComponent } from './help-tour.component';
+import { HelpTourService } from '../../services/help-tour.service';
+
+describe('HelpTourComponent', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ TestBed.resetTestingModule();
+ TestBed.configureTestingModule({
+ declarations: [HelpTourComponent],
+ imports: [OverlayModule],
+ providers: [{ provide: TranslateService, useValue: { currentLang: 'en-US' } }],
+ });
+ });
+
+ it('does not mark the tour seen just by being mounted', () => {
+ const fixture = TestBed.createComponent(HelpTourComponent);
+ fixture.componentInstance.tour = 'page';
+ fixture.detectChanges();
+ expect(TestBed.inject(HelpTourService).hasSeen('page')).toBe(false);
+ });
+
+ it('shows no card while no tour is running', () => {
+ const fixture = TestBed.createComponent(HelpTourComponent);
+ fixture.detectChanges();
+ expect(fixture.componentInstance.state).toBeNull();
+ });
+});
+```
+
+- [ ] **Step 7: Declare `HelpTourComponent` in `time-planning-pn.module.ts`**
+
+- [ ] **Step 8: Run the tests and confirm they pass**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: PASS.
+
+- [ ] **Step 9: Pre-commit gate** — code-reviewer and code-simplifier in parallel; resolve findings.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add eform-client/src/app/plugins/modules/time-planning-pn/help \
+ eform-client/src/app/plugins/modules/time-planning-pn/time-planning-pn.module.ts \
+ eform-client/src/app/plugins/modules/time-planning-pn/i18n
+git commit -m "feat(help): add guided tour that skips steps with no anchor"
+```
+
+---
+
+### Task 9: Wire the surfaces into the page
+
+**Files:**
+- Modify: `components/plannings/time-plannings-container/time-plannings-container.component.html` (toolbar `?` button after the `div.line-vert` at :78; `data-tp-help` on the toolbar controls; mount `tp-help-panel` and `tp-help-tour`)
+- Modify: `components/plannings/time-plannings-container/time-plannings-container.component.ts` (open panel, start page tour once)
+- Modify: `components/plannings/time-plannings-table/time-plannings-table.component.html` (`data-tp-help` anchors, `tp-help-hint` under the grid)
+- Modify: `components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html` (`tp-help-icon` on the field groups, `data-tp-help` anchors, `tp-help-hint` for the future-date case, `tp-help-tour` for the dialog tour)
+- Modify: `components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.ts` (start the dialog tour once)
+- Test: `help/help-wiring.spec.ts`
+
+**Interfaces:**
+- Consumes: everything from Tasks 5-8.
+- Produces: no new exports. This task is additive markup plus two small container methods.
+
+- [ ] **Step 1: Write the failing wiring test**
+
+This is the test that stops the anchors rotting. It reads the templates off disk and asserts each side of the contract.
+
+```ts
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { PLANNING_HELP_ENTRIES } from './planning-help.registry';
+
+const MODULE_ROOT = join(__dirname, '..');
+
+const TEMPLATES = [
+ 'components/plannings/time-plannings-container/time-plannings-container.component.html',
+ 'components/plannings/time-plannings-table/time-plannings-table.component.html',
+ 'components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html',
+].map(relative => readFileSync(join(MODULE_ROOT, relative), 'utf8'));
+
+const MARKUP = TEMPLATES.join('\n');
+
+describe('help wiring', () => {
+ it('anchors every entry that a tour needs', () => {
+ for (const entry of PLANNING_HELP_ENTRIES.filter(e => e.tourStep !== undefined)) {
+ expect(MARKUP).toContain(`data-tp-help="${entry.anchor}"`);
+ }
+ });
+
+ it('only uses helpIds that exist in the registry', () => {
+ const known = new Set(PLANNING_HELP_ENTRIES.map(e => e.id));
+ const used = [...MARKUP.matchAll(/helpId="([^"]+)"/g)].map(match => match[1]);
+ expect(used.length).toBeGreaterThan(0);
+ for (const id of used) {
+ expect(known.has(id as never)).toBe(true);
+ }
+ });
+
+ it('only uses anchors that exist in the registry', () => {
+ const known = new Set(PLANNING_HELP_ENTRIES.map(e => e.anchor).filter(Boolean));
+ const used = [...MARKUP.matchAll(/data-tp-help="([^"]+)"/g)].map(match => match[1]);
+ for (const anchor of used) {
+ expect(known.has(anchor)).toBe(true);
+ }
+ });
+
+ it('mounts the panel and both tours exactly once', () => {
+ expect((MARKUP.match(/ {
+ for (const id of ['flex.whatIsFlex', 'flex.sumFlex', 'flex.paidOutFlexRelation']) {
+ expect(MARKUP).toContain(`data-tp-help="${id}"`);
+ }
+ });
+
+ it('starts each tour from a component, since mounting alone does not', () => {
+ const containerTs = readFileSync(join(MODULE_ROOT,
+ 'components/plannings/time-plannings-container/time-plannings-container.component.ts'), 'utf8');
+ const dialogTs = readFileSync(join(MODULE_ROOT,
+ 'components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.ts'), 'utf8');
+ expect(containerTs).toMatch(/start\(\s*'page'/);
+ expect(dialogTs).toMatch(/start\(\s*'dialog'/);
+ });
+
+ it('never uses the translate pipe inside help templates', () => {
+ const helpTemplates = [
+ 'help/components/help-panel/help-panel.component.html',
+ 'help/components/help-icon/help-icon.component.html',
+ 'help/components/help-tour/help-tour.component.html',
+ 'help/components/help-hint/help-hint.component.html',
+ ].map(relative => readFileSync(join(MODULE_ROOT, relative), 'utf8')).join('\n');
+ expect(helpTemplates).not.toContain('| translate');
+ });
+
+ it('binds the help-icon and panel outputs, or they are inert', () => {
+ expect(MARKUP).toContain('(openInPanel)=');
+ expect(MARKUP).toContain('(replayTourRequested)=');
+ });
+
+ it('does not introduce new translate keys for help chrome', () => {
+ // The help button's tooltip must come from HelpUiStrings, not a new shared key.
+ expect(MARKUP).not.toContain("'Help' | translate");
+ });
+});
+```
+
+- [ ] **Step 2: Run it and confirm it fails**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn/help`
+Expected: FAIL — no `data-tp-help` attributes exist yet.
+
+- [ ] **Step 3: Add the `?` button and mounts to the container template**
+
+After the last `div.line-vert` (currently line 78), as a sibling of the existing icon buttons:
+
+```html
+
+```
+
+Add `data-tp-help` to the toolbar controls that carry an anchor: `toolbar.showResigned`, `toolbar.navBackward`, `toolbar.navForward`, `toolbar.workerFilter`, `toolbar.tagFilter`, `toolbar.dateRange`, `toolbar.downloadExcel`, `toolbar.payrollExport`, `toolbar.reload`.
+
+At the end of the container template, outside `eform-new-subheader`:
+
+```html
+
+
+```
+
+Every `tp-help-icon` on the page binds its `openInPanel` output so the popover's
+"More in help" link actually opens the panel on that entry:
+
+```html
+
+```
+
+- [ ] **Step 4: Add the two container methods**
+
+In `time-plannings-container.component.ts`, injecting `HelpContentService`, `HelpPanelService` and `HelpTourService`:
+
+```ts
+get helpUi(): HelpUiStrings {
+ return this.helpContent.ui();
+}
+
+openHelp(target?: HelpEntryId): void {
+ this.helpPanel.open(target);
+}
+
+replayPageTour(): void {
+ // The panel has already closed itself; let that settle before querying anchors.
+ setTimeout(() => this.helpTour.start('page', { isAdmin: this.isAdmin }));
+}
+
+private startTourOnce(): void {
+ if (!this.helpTour.hasSeen('page')) {
+ setTimeout(() => this.helpTour.start('page', { isAdmin: this.isAdmin }));
+ }
+}
+```
+
+Call `startTourOnce()` at the end of the existing plannings-loaded handler, so the grid is rendered and the anchors exist. The `setTimeout` lets the current change-detection pass finish before the DOM is queried.
+
+- [ ] **Step 5: Add anchors and the hint to the table template**
+
+`data-tp-help` on: the pinned name cell (`grid.nameColumn`), the tag chips (`grid.tagChips`), the settings strip (`grid.settingsStrip`), a day cell (`grid.dayCellAnatomy` and `grid.openDay`), the weekly total (`grid.weeklyPlannedHours`), the message icons (`grid.messageIcons`), the name column header (`grid.sortName`).
+
+Under the grid:
+
+```html
+
+```
+
+- [ ] **Step 6: Add icons, anchors, hints and the dialog tour to the workday dialog**
+
+`tp-help-icon` beside the Planned group (`dayCell.plannedTimes`), the Registered group (`dayCell.actualTimes`), the registered pause (`dayCell.resetPauseToRecorded`), Plan hours (`dayCell.planHours`), Netto override (`dayCell.nettoOverride`), Paid-out flex (`dayCell.paidOutFlex`), the day-type checkboxes (`dayCell.flags`), **the Save button (`dayCell.save`)**, the version-history button (`dayCell.versionHistory`), the shift rows (`dayCell.shiftCount`), a per-field reset (`dayCell.resetField`), the GPS button (`dayCell.gps`), the snapshot button (`dayCell.snapshot`), and the timepickers (`dayCell.oneMinuteIntervals`). Matching `data-tp-help` on each.
+
+`dayCell.save` is not optional: it is `tourStep: 6` of the dialog tour, and Step 1's wiring test asserts an anchor exists for every entry carrying a `tourStep`.
+
+The three flex entries get icons and anchors too, next to the figures they explain — `flex.whatIsFlex` and `flex.paidOutFlexRelation` beside the paid-out-flex field in this dialog, and `flex.sumFlex` beside the flex sum. These are the numbers the spec calls out as most likely to mislead, so reaching them only through the panel would miss the point.
+
+Then, at the end of the dialog template:
+
+```html
+
+
+```
+
+`tp-help-tour` takes `[tour]` only. It has no `isAdmin` input — admin filtering happens inside `HelpTourService.start(tour, { isAdmin })`, which the container and the dialog each call. Each mounted instance renders only its own tour, so the page and dialog instances do not collide.
+
+- [ ] **Step 6b: Start the dialog tour**
+
+Mounting `tp-help-tour` only subscribes to state — nothing starts a tour. Without this the dialog tour can never fire. In `workday-entity-dialog.component.ts`, injecting `HelpTourService`:
+
+```ts
+private startDialogTourOnce(): void {
+ if (!this.helpTourService.hasSeen('dialog')) {
+ setTimeout(() => this.helpTourService.start('dialog', { isAdmin: false }));
+ }
+}
+```
+
+Call it at the end of `ngOnInit`, after the form is built, so the anchors exist in the DOM.
+
+If the dialog tears the tour down explicitly when it closes, it must call
+`HelpTourService.abort()`, **not** `stop()`. `stop()` marks the tour seen — it is the
+user-initiated end, used by Skip, Escape and completion. `abort()` ends the tour without
+marking it seen, and is for the page changing underneath: someone who opens a row,
+glances and closes it has not seen the tour and must still be offered it.
+
+- [ ] **Step 7: Run the tests and confirm they pass**
+
+Run: `cd eform-angular-frontend/eform-client && npx jest --testPathPatterns=time-planning-pn`
+Expected: PASS — the whole plugin suite, to prove nothing else regressed.
+
+- [ ] **Step 8: Verify the build compiles**
+
+Run: `cd eform-angular-frontend/eform-client && npx ng build --configuration development`
+Expected: build succeeds. Template errors do not surface in Jest, so this step is required before the commit.
+
+- [ ] **Step 9: Pre-commit gate** — code-reviewer and code-simplifier in parallel; resolve findings.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add eform-client/src/app/plugins/modules/time-planning-pn
+git commit -m "feat(help): wire help icon, panel, tours and hints into the planning page"
+```
+
+---
+
+### Task 10: Ship
+
+- [ ] **Step 1: Push the branch**
+
+```bash
+cd /home/rene/Documents/workspace/microting/eform-angular-timeplanning-plugin
+git push -u origin feat/planning-help-system
+```
+
+- [ ] **Step 2: Open the PR toward `stable`**
+
+```bash
+gh pr create --base stable --title "feat(help): searchable in-page help for the planning page" --body "..."
+```
+
+- [ ] **Step 3: Watch CI**
+
+```bash
+gh pr checks --watch
+```
+
+The `angular-unit-test` job runs the new specs. If it fails, investigate — do not rewrite existing tests to make it pass. Only fix tests added by this plan. After any fix, re-run the pre-commit gate before committing.
+
+- [ ] **Step 4: Merge once green**
+
+---
+
+## Self-Review
+
+**Spec coverage.** Content model → Task 1. Locale coverage and fallback → Tasks 2, 3. Search → Task 4. ⓘ icon → Task 5. Inline hint → Task 6. Side panel → Task 7. Tours and anchor-skipping → Task 8. Anchoring and template wiring → Task 9. Admin filtering → covered by tests in Tasks 2, 4, 7, 8. Copy rules → enforced by the banned-word tests in Tasks 1 and 3. Testing section → each task's tests. Out-of-scope items → Global Constraints.
+
+**Deviation from the spec, recorded deliberately.** The spec's `HelpSection` union listed `shifts` and `flags`; no entry uses them, so this plan omits both. The spec also described the ⓘ overlay as using `cdkConnectedOverlayUsePopover="inline"`; that input does not exist in CDK 20.2.14, and the spec has been corrected — this plan uses a standard `cdkConnectedOverlay`.
+
+**Fixed after review.** Both reviewers ran against the first draft of this plan; these are the changes their findings produced.
+
+- The local test loop did not work at all. Jest runs from the frontend repo and its `testMatch` is scoped to that `rootDir`, so specs written only in the plugin repo were never discovered — every "run it and confirm it fails" step would have reported `No tests found`. Task 0 now establishes the `--roots` invocation and the `node_modules` symlink it needs, both verified end to end with a throwaway Angular TestBed spec before this plan was finalised.
+- The plan contradicted its own constraint by adding UI labels to the 25 shared locale files. Those labels are now `HelpUiStrings` in `help/i18n/`, and a wiring test asserts no help template uses the `translate` pipe.
+- The dialog tour could never start — mounting `tp-help-tour` only subscribes. Task 9 Step 6b adds the trigger, the dialog `.ts` is now in Task 9's file list, and a wiring test asserts both tours are started from a component.
+- "Replayable from the panel" was specified but never built. The panel now has a replay action.
+- `HelpTourComponent` marked the tour seen at mount, because `state$` replays `null` to new subscribers — which would have suppressed the automatic first run for every genuine first-time user. Recording moved into the service, guarded so a tour that could not start is not marked seen, with four service tests and a component regression spec.
+- `dayCell.save` was required by the dialog tour and by Task 9's own wiring test, but Step 6 never anchored it. The three `flex.*` entries were reachable only through the panel, despite being the numbers the spec calls most misleading. Both now anchored.
+- The "ranks tasks above controls" test was vacuous when a query returned only tasks; it now asserts both groups are present first.
+- The Danish banned-word regex missed `administratoren` and `administratorens`, the forms most likely to be written. Now `\badministrator\w*\b`.
+- Three tests asserted prose text that Task 1 never mandates ("Date range", "future"), so a copywriting choice could fail them. They now compare against the content file.
+- Corrected line citations and one overstatement: the `.help-text` pattern is used twice in this plugin, not ~8 times.
+
+**Type consistency.** `HelpEntryId`, `HelpEntry`, `HelpProse`, `HelpProseMap` are defined once in Task 1 and used unchanged thereafter. `HelpContentService.prose/entry/entries/tourEntries/localeProse` are consumed with those exact names in Tasks 4, 5, 6, 7, 8. `HelpSearchResult` is defined in Task 4 and consumed in Task 7. `HelpTourState` and `TOUR_STORAGE_KEY` are defined in Task 8 and used in its own component and spec. `HelpPanelService.open/close/isOpen$/target$` are defined in Task 7 and called from Task 9.
+
+**One deliberate content decision.** Tasks 1 and 3 each write 48 prose entries. The plan gives the complete id list, the enforced authoring rules, the machine-checked constraints, and fully worked exemplars of every shape (task with steps and detail, control with detail, control without). Writing the remaining entries is the content work itself, not a placeholder — and the registry spec fails until all 48 exist, so completeness is verified rather than assumed.
diff --git a/docs/superpowers/specs/2026-09-04-planning-help-system-design.md b/docs/superpowers/specs/2026-09-04-planning-help-system-design.md
new file mode 100644
index 00000000..4e60ad55
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-04-planning-help-system-design.md
@@ -0,0 +1,394 @@
+# In-page help system for the planning page
+
+**Date:** 2026-09-04
+**Status:** Design approved, implementation plan not yet written
+**Scope:** `plugins/time-planning-pn/planning` only
+
+## Problem
+
+A team lead or planner opens the planning page and can edit almost everything on it,
+but nothing on the page explains the rules they are editing against. Flex, pauses,
+netto hours, the difference between planned and actual times, what saving actually
+triggers — none of it is written down anywhere the user can reach. Customer support
+answers the same questions repeatedly.
+
+The page carries 75 `matTooltip`s, but they are icon labels ("Download Excel",
+"Reload table"), not explanations. There is no help affordance of any kind — no `?`
+button, no popover, no tour — anywhere in either repo.
+
+## Audience
+
+Primary: the **team lead / planner** — a non-admin who plans hours for a group of
+workers, can edit rows, and does not know the rules.
+
+Secondary: **customer support and onboarding** — the goal is that an answer written
+once appears everywhere a user might look for it.
+
+## What a non-admin can actually do
+
+The planning page is **not admin-gated**. Its route guard requires only the
+`time_planning_plugin_access` claim (`time-planning-pn.routing.ts:19-24`). Inside the
+page, exactly two things are admin-only:
+
+| Control | Gate |
+|---|---|
+| Export to payroll button | `time-plannings-container.component.html:88`, and server-side via `PayrollExportController.cs:12` |
+| Assigned-site dialog (click on worker name) | `time-plannings-table.component.ts:370-372`, **client-side only** — the endpoint it calls checks the `GetWorkingHours` claim, not the admin role |
+
+Everything else — filters, navigation, Excel download, reload, and the entire day-cell
+editor — is available to any user who can load the page. That editor,
+`WorkdayEntityDialogComponent`, is a 2001-line component with up to five shifts of
+planned and actual times, per-field resets, GPS and snapshot viewers, plan hours,
+netto override, paid-out flex, flag checkboxes and comments. It is where a planner is
+lost, and it is therefore the centre of gravity for this work.
+
+## Approach
+
+One **help registry** defines every explainable thing on the page. Four surfaces read
+from it. Support edits an answer once and it appears in all four.
+
+Rejected alternatives:
+
+- **Flat translate keys in the existing locale files.** No new machinery, but it
+ roughly doubles each of the 25 locale files, buries UI labels among prose, and makes
+ every wording tweak a 25-file diff.
+- **Backend-served help content.** Editable without a release, but requires a new API,
+ table and migration in a `-base` repo, which base dev mode cannot touch.
+
+## Content model
+
+`time-planning-pn/help/planning-help.registry.ts` — structure only, no prose:
+
+```ts
+export type HelpSection =
+ | 'task' | 'toolbar' | 'grid' | 'dayCell' | 'shifts' | 'flex' | 'flags';
+
+export type HelpKind = 'control' | 'task';
+
+export interface HelpEntry {
+ id: HelpEntryId; // stable identifier, e.g. 'dayCell.actualPause'
+ kind: HelpKind;
+ section: HelpSection;
+ anchor?: string; // data-tp-help value; required if tourStep is set
+ tourStep?: number; // present = included in a tour; value = order within it
+ tour?: 'page' | 'dialog';
+ adminOnly?: boolean; // filtered out when the current user is not an admin
+ related?: HelpEntryId[]; // tasks only: the controls the task touches
+}
+```
+
+Prose lives separately, in `help/i18n/enUS.ts` and `help/i18n/da.ts`:
+
+```ts
+export const enUS: Record = { ... };
+```
+
+`short` is one or two sentences and is what the ⓘ popover and the panel summary show.
+`detail` is an optional further paragraph shown only in the panel.
+
+### Controls and tasks
+
+A **control** entry answers "what is this thing?" and is anchored to something on
+screen. A **task** entry answers "how do I do X?", has ordered `steps`, and is anchored
+to nothing.
+
+Both are needed, and the distinction is what makes the panel searchable. A planner who
+needs to register vacation does not search for a control — no control on the page is
+called "vacation". They search for the task. Control entries alone would return
+nothing for the most common question the page receives.
+
+Tours are built from control entries only; tasks have no `anchor` and no `tourStep`.
+
+`HelpContentService` resolves prose against ngx-translate's `currentLang` and falls
+back to English **per entry**, so a partially translated Danish file degrades
+entry-by-entry rather than all-or-nothing.
+
+The existing 25 locale files under `time-planning-pn/i18n/` are not modified.
+
+### Locale coverage
+
+English and Danish are authored properly. The other 23 locales fall back to English.
+Adding a locale later is a pure content commit — a new file under `help/i18n/`, no code
+change. Machine-translating ~1750 strings up front was rejected as worse than honest
+English.
+
+## The four surfaces
+
+| Surface | Component | Reads |
+|---|---|---|
+| ⓘ icon | `` | `short` |
+| Side panel | `` | all entries, grouped by `section` |
+| Tour | `HelpTourService` | entries with `tourStep`, positioned via `anchor` |
+| Inline hint | `` | `short` |
+
+**ⓘ icon.** A small `mat-icon-button` whose `aria-label` comes from the entry. Opens a
+`cdkConnectedOverlay` anchored to the button via `cdkOverlayOrigin`, with a
+close-on-scroll strategy and fallback positions. Dismissed on Escape
+(`overlayKeydown`), an outside click (`overlayOutsideClick`), and scroll.
+
+Deliberately **no backdrop**. A transparent full-page backdrop swallows the first
+click, and on this page every day cell is a click target that opens the day editor —
+so a planner dismissing a popover would have to click twice to reach the cell
+underneath. `overlayOutsideClick` gives the same dismissal without the tax.
+
+This has to work inside a `MatDialog`, because roughly half the help lives in one. It
+does: CDK appends every overlay to the same `.cdk-overlay-container`, and an overlay
+opened while a dialog is up is appended after the dialog pane, so it stacks above it.
+The proof is already in these two dialogs — `AssignedSiteDialogComponent` and
+`WorkdayEntityDialogComponent` between them host 23 overlay-based controls
+(`ngx-material-timepicker`, `matDatepicker`, `mtx-select`) that open correctly today.
+
+Note for the implementer: `cdkConnectedOverlayUsePopover` (native top-layer rendering)
+does **not** exist in the installed `@angular/cdk` **20.2.14** — it is a later addition.
+Do not reach for it; the standard overlay container behaviour described above is what
+this design relies on.
+
+**Search.** A field at the top of the panel, focused when the panel is opened from the
+`?` button. With no query the panel shows its normal grouped browse view; search is
+additive, never a replacement for browsing.
+
+Matching is case-insensitive and diacritic-insensitive — Danish `å æ ø` must fold, or
+a user typing `laege` finds nothing — across `title`, `keywords`, `short`, `detail` and
+`steps`. It runs against **both the active locale and the English fallback**, so a
+Danish user who types an English term still finds the entry, and vice versa. Both are
+already loaded, so this costs nothing.
+
+Matching is substring, not fuzzy. Across ~48 entries fuzzy matching adds noise rather
+than recall.
+
+Results are ordered: **tasks before controls** — someone typing into a help box wants a
+how-to, not a definition — then by where the match landed, title before keyword before
+body. Each result shows its `title` and `short`; expanding a task reveals its `steps`.
+
+When nothing matches, the panel names the query and lists the tasks rather than showing
+an empty result — a dead end is the one outcome a help search must not produce.
+
+`keywords` is what makes this work at all. A Danish planner types *ferie*, *sygdom*,
+*fri*, *afspadsering* or *barsel*, and none of those strings appear anywhere in the
+English prose. Keywords carry the synonyms, per locale, and are authored as
+deliberately as the prose.
+
+**Side panel.** A right-side slide-in opened by a single `?` button placed in the
+container toolbar after the last `div.line-vert`
+(`time-plannings-container.component.html:78`), styled
+`btn-secondary--icon-rounded-border` to match the five icon buttons already there.
+Entries render grouped by section in registry order. Opening the panel from an ⓘ's
+"More" link scrolls to that entry.
+
+**Tour.** `HelpTourService` walks entries with a `tourStep`, positioning the same CDK
+overlay against `[data-tp-help=""]`. Runs once automatically per user
+(`localStorage` key `tp.planning.tour.v1`) and is replayable from the panel. **A step
+whose anchor is absent from the DOM is skipped, not treated as an error** — this is
+required, because the worker select only renders when `availableSites.length > 1` and
+the payroll button only renders for admins.
+
+**Inline hint.** Renders the plugin's existing `div.help-text` pattern — a
+`mat-icon>info` beside a span. It is used in exactly two places today
+(`pay-day-rule-form.component.html:105-108` and
+`day-type-rule-dialog.component.html:161`), so this work both reuses and
+standardises it. Used where the page currently explains
+nothing:
+
+- Fields disabled because the date is in the future
+- The "Total planned hours cannot exceed 24" validation
+- An empty grid when filters match no workers
+- **The worker column**, which packs four unlabelled things into one cell — name,
+ agreed weekly hours, tags, and a strip of status icons for the rules that apply to
+ that worker. The hint names what is being shown.
+
+## Anchoring
+
+Anchors are `data-tp-help=""` **attributes added to templates**, never CSS
+selectors. `mtx-grid` regenerates DOM and its class names are shared across columns, so
+selector-based anchoring would be silently fragile. This adds roughly 35 attributes
+across the container, table and workday-dialog templates. It is the only invasive part
+of the change, and it is purely additive — attributes and ⓘ elements, with no logic
+touched.
+
+**Two tours, not one.** A tour cannot span the page and a modal in a single run. The
+`page` tour covers the toolbar and grid and ends by inviting the user to open a day.
+The `dialog` tour is offered from inside `WorkdayEntityDialogComponent`.
+
+## Entry inventory
+
+Approximately 48 entries — 36 controls and 12 tasks.
+
+### `task` (12)
+
+`registerVacation`, `registerSickness`, `registerDayOff`, `correctRegisteredTime`,
+`addMissingRegistration`, `addExtraShift`, `changePlannedHours`, `payOutFlex`,
+`exportForPayroll`, `whoChangedThis`, `whereWasThisRegistered`, `filterToOneTeam`.
+
+Each carries `steps` and a `related` list of the controls it touches, so a task ends by
+pointing at the control entries that explain the fields it just told the user to fill.
+
+Three of these describe the day flags, and they carry a rule the UI actively hides.
+The flags render as checkboxes but are **mutually exclusive** — ticking one unticks the
+rest — and ticking one rewrites netto hours
+(`workday-entity-dialog.component.ts:1263-1290`):
+
+| Flag | Resulting netto hours |
+|---|---|
+| `DayOff`, `VacationDayOff` | `0` |
+| `Vacation`, `Sick`, `Course`, `LeaveOfAbsence`, `Maternity`, `Holiday`, and the rest | the day's planned hours |
+
+The trap is **name versus behaviour**, not adjacency. In render order the types are
+`DayOff`, `Vacation`, `Sick`, `Course`, `LeaveOfAbsence`, `Children1stSick`,
+`Children2stSick`, `TimeOff`, `Maternity`, `VacationDayOff`, `Holiday`,
+`PregnancyLeave` — so `Vacation` (2nd) and `VacationDayOff` (10th) are nowhere near
+each other. What actually catches people is that **`TimeOff` keeps the planned hours**
+while the similarly-named `DayOff` and `VacationDayOff` zero them.
+
+It is worse in Danish, where the shipped labels are `Fridag` (DayOff, zero),
+`Afspadsering` (VacationDayOff, zero) and **`Ferie fridag` (TimeOff, keeps the hours
+despite being named a fridag)**.
+
+`registerVacation`, `registerDayOff` and `dayCell.flags` must state which types count
+as worked time; this is the single most valuable thing the help system can say.
+
+The full flag set is `TimePlanningMessagesEnum`: `DayOff`, `Vacation`, `Sick`,
+`Course`, `LeaveOfAbsence`, `Children1stSick`, `Children2stSick`, `TimeOff`,
+`Maternity`, `VacationDayOff`, `Holiday`, `PregnancyLeave`. `Blank` and `Care` are
+excluded from the UI (`:242`) and get no entries. Note that `Care` is not a member of
+`TimePlanningMessagesEnum` at all — that half of the check is dead defensive code.
+
+### `toolbar` — controls (9)
+
+`showResigned`, `navBackward`, `navForward`, `workerFilter`, `tagFilter`, `dateRange`,
+`downloadExcel`, `payrollExport` (adminOnly), `reload`.
+
+### `grid` — controls (8)
+
+`nameColumn`, `tagChips` (click-to-filter), `settingsStrip` (the pay-rule /
+mobile-registration / over-midnight / auto-break / one-minute / extra-shifts status
+badges), `dayCellAnatomy` (planned versus actual, and the icon legend),
+`weeklyPlannedHours`, `messageIcons`, `sortName`, `openDay`.
+
+`weeklyPlannedHours` deserves care: the page renders **two different** `plannedHours`
+elements — a weekly total and a per-day-cell value. The help text must name which one
+it describes, or it will actively mislead.
+
+### `dayCell` — controls (16)
+
+`versionHistory`, `plannedTimes`, `actualTimes`, `shiftCount`, `resetField`,
+`resetPauseToRecorded`, `gps`, `snapshot`, `futureDisabled`, `planHours`,
+`nettoOverride`, `paidOutFlex`, `flags`, `commentOffice`, `save`,
+`oneMinuteIntervals` (the timepicker's `minutesGap` is 1 or 5 depending on the
+worker's setting).
+
+### `flex` — controls (3)
+
+`whatIsFlex`, `sumFlex`, `paidOutFlexRelation`.
+
+The flex entries must describe **what the user sees and controls**, not restate the
+server's arithmetic. The `SumFlexEnd - PaiedOutFlex` calculation is duplicated in
+roughly five places in the backend and `PaiedOutFlexInSeconds` is frequently
+unpopulated, so help text asserting a precise formula risks contradicting what the
+page actually displays for a given worker.
+
+## Admin-awareness
+
+Exactly one entry carries `adminOnly`: `toolbar.payrollExport`. The panel and both
+tours filter it through `selectAuthIsAdmin$` (`auth.selector.ts:17-18`).
+
+`grid.nameColumn` is not `adminOnly` — it describes what the column *displays*, which
+every user sees. It says nothing about the dialog behind it.
+
+Every other entry is shown to all users, which matches how the page is actually gated.
+
+## Rollout: admin-only first
+
+The whole help system — the `?` button, the panel, both tours, every ⓘ and every inline
+hint — is currently visible only to admins, i.e. only to Microting. This is a staged
+rollout, not a change of audience: the content is still written for the team lead, and the
+copy rules below still bind, because customers see it when the gate lifts.
+
+The gate lives in three choke points rather than at the ~20 template call sites, so no
+usage site can leak: `HelpVisibilityService` (root, live subscription to
+`selectCurrentUserIsAdmin` — never `take(1)`, which would latch a stale value),
+read by `HelpEntryChromeBase.prose`, by `HelpTourService.start()`, and by
+`HelpPanelComponent`. A tour refused by the gate is deliberately **not** marked seen, so a
+user still gets their one automatic offer once the gate is lifted.
+
+Lifting the gate should be a small change in those three places plus the `?` button. Two
+things to revisit at that point:
+
+- `grid.nameColumn`'s copy currently under-describes its only remaining audience — it never
+ says that clicking the column opens the worker's settings. That sentence must not be
+ added while the gate is up, and if it is ever added it must not be phrased as an
+ administrator capability.
+- `toolbar.payrollExport` keeps its own `adminOnly` flag, which is a permanent property of
+ that entry rather than part of this rollout.
+
+## Copy rules
+
+**"Admin" means Microting, not a customer role.** Help copy therefore never mentions
+administrator capabilities, never explains what someone with more access could do, and
+never accounts for why a control did nothing. An entry describes what the reader sees
+and what the reader can do — nothing else.
+
+This rules out a whole tempting category of text. The worker column is the clearest
+case: clicking it opens a settings dialog for Microting staff and silently does nothing
+for everyone else, and the entry must still confine itself to describing the four
+things the column displays. "This opens worker settings for administrators" is exactly
+the sentence not to write.
+
+Two further rules, both already exercised above:
+
+- Name which value is meant when a label is reused. `plannedHours` renders as both a
+ weekly total and a per-day-cell value.
+- Describe what the screen shows, not how the server computes it — see the flex note
+ under the entry inventory.
+
+## Testing
+
+- **`HelpContentService` fallback** — an entry missing from `da.ts` resolves to the
+ English text; a present entry does not.
+- **Registry integrity** — every entry with a `tourStep` also declares a `tour` and an
+ `anchor`; no `task` entry has an `anchor` or a `tourStep`; every `related` id resolves;
+ every entry has at least one keyword in `enUS`; `tourStep` values are unique within each tour; every `helpId` referenced in
+ a template exists in the registry; every registry id has prose in `enUS`. This is the
+ test that prevents rot: it fails when someone typos an id, or deletes a control and
+ leaves its help entry behind.
+- **Search** — a Danish query folds diacritics, asserted against a term that actually
+ appears in the content (`lon` finds the entries keyworded *løn*) and asserting a
+ non-empty result, since two queries that both match nothing compare equal regardless
+ of whether folding works; an English query
+ finds a Danish-only entry through the English fallback; tasks sort above controls; a
+ query matching nothing returns the task list rather than an empty result.
+- **Admin filtering** — a non-admin sees neither `adminOnly` entry in the panel, and
+ the page tour skips the payroll step.
+
+No end-to-end tests. Per the project's standing practice, changes are pushed and
+verified in CI rather than run locally.
+
+## Out of scope
+
+- Any backend change, API, or migration
+- Any new npm dependency — no tour library exists in either repo, and the tour is
+ roughly 200 lines over the CDK overlay that Angular Material 20.2.14 already provides
+- Any change to `eform-angular-frontend` or `eform-shared`. The plugin repo contains
+ only `src/app/plugins/`, with no `src/app/common`, so the help system lives entirely
+ inside `time-planning-pn/` — which is also correct, since it then ships and versions
+ with the plugin
+- Any change to the 25 existing locale files
+- The admin-only settings pages (pay rule sets, break policies) — separate pages,
+ separate scope
+
+## Implementation note: repository state
+
+The host-app mirror at
+`eform-angular-frontend/eform-client/src/app/plugins/modules/time-planning-pn/` is
+**behind** this repository by 68 files, including the tag-chip click-to-filter feature,
+the settings-strip status icons, and all 20 shared i18n files. Running
+`devgetchanges.sh` would therefore copy stale host files over this repo and delete
+those features.
+
+All work for this design happens **directly in this repository**. The host mirror is
+not edited, and `devgetchanges.sh` is not run.
diff --git a/eform-client/playwright.config.ts b/eform-client/playwright.config.ts
index 64b24ee1..04a999fb 100644
--- a/eform-client/playwright.config.ts
+++ b/eform-client/playwright.config.ts
@@ -13,6 +13,15 @@ export default defineConfig({
retries: 0,
use: {
baseURL: 'http://localhost:4200',
+ // Seeds localStorage so the planning page's onboarding tours count as already
+ // seen. Playwright gives every test a fresh context with empty storage, so
+ // without this both tours auto-start: the page tour drops a card over the top
+ // grid rows and the dialog tour drops one over the shift-1 fields, and
+ // Playwright's actionability check then fails on the intercepting overlay for
+ // every spec that clicks a day cell or #saveButton. The seed matches
+ // TOUR_STORAGE_KEY in help/services/help-tour.service.ts; a jest test in the
+ // plugin (help/playwright-tour-seed.spec.ts) fails if the two drift apart.
+ storageState: 'playwright/helpers/tour-seen.storage.json',
viewport: { width: 1920, height: 1080 },
video: 'on',
screenshot: 'only-on-failure',
diff --git a/eform-client/playwright/helpers/tour-seen.storage.json b/eform-client/playwright/helpers/tour-seen.storage.json
new file mode 100644
index 00000000..f98d4dd9
--- /dev/null
+++ b/eform-client/playwright/helpers/tour-seen.storage.json
@@ -0,0 +1,14 @@
+{
+ "cookies": [],
+ "origins": [
+ {
+ "origin": "http://localhost:4200",
+ "localStorage": [
+ {
+ "name": "tp.planning.tour.v1",
+ "value": "[\"page\",\"dialog\"]"
+ }
+ ]
+ }
+ ]
+}
diff --git a/eform-client/src/app/plugins/modules/time-planning-pn/components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html b/eform-client/src/app/plugins/modules/time-planning-pn/components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html
index e690e94e..1f6b06d7 100644
--- a/eform-client/src/app/plugins/modules/time-planning-pn/components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html
+++ b/eform-client/src/app/plugins/modules/time-planning-pn/components/plannings/time-planning-actions/workday-entity/workday-entity-dialog.component.html
@@ -5,10 +5,12 @@
({{ data.planningPrDayModels.id }})
+