Portfolio/AGENTS.md

AGENTS.md

Contributor and agent guide for this repository. Read this before changing routing, copy, styles, or SSR behaviour.

Purpose

This is a bilingual portfolio for a software/DevOps engineer. German is the default language and is served at /. English is the full second version and is served under /en. Home is the direct-customer experience. /pitch is the recruiter-oriented page and is reachable without sitting in the primary navigation. Every public page exists in both locales.

Architecture

• Angular 21 standalone components, no NgModules
• Zoneless change detection
• Signals for local state
• Lazy-loaded feature routes
• SSR with prerendering (@angular/ssr, outputMode: "server")
• Express host in src/server.ts

Directory map

Path	Role
src/app/core/**	Contracts, services and tokens. No UI.
src/app/features/**	Routed page components, one folder per route.
src/app/shared/**	Reusable UI primitives used by multiple features.
src/app/components/**	Existing decorative/feature widgets (skills grid, dot background).
public/**	Static SVG and public assets copied as-is.
src/styles.scss	Global design tokens and primitives. The only place raw brand hex values are defined.
src/_breakpoints.scss	Breakpoint map (sm 40rem, md 48rem, lg 64rem, xl 80rem) and the respond-to mixin. Components pull it in with @use 'breakpoints'.

Commands

Script	Purpose
npm start	Dev server (ng serve).
npm run build	Production build (default configuration).
npm run watch	Development rebuild on change.
npm test	Unit tests in watch mode.
npm run test:ci	Unit tests once (--watch=false); must exit.
npm run lint	ESLint over the workspace.
npm run lint:fix	ESLint with autofix.
npm run format	Prettier write.
npm run format:check	Prettier check (CI).
npm run serve:ssr	Serve the production SSR bundle.
npm run serve:ssr:Portfolio	Alias of serve:ssr for existing tooling.
npm run e2e	Playwright + axe-core against the SSR bundle.
npm run e2e:install	Install the pinned Chromium build.
npm run lighthouse	Production build, then Lighthouse CI.
npm run ci	lint, format:check, test:ci, then build.

Code conventions

• Standalone components only
• inject() over constructor injection for new code
• Signals over RxJS for local state
• ChangeDetectionStrategy.OnPush on new components
• kebab-case file names
• No any
• No default exports
• Templates in separate files

SCSS conventions

• Global design tokens live only in src/styles.scss as CSS custom properties
• Components consume var(--...) and never redefine raw hex values
• Use the documented spacing (--space-1 … --space-12) and typography (--text-xs … --text-3xl) scale
• Hover-only affordances must be wrapped in @media (hover: hover) and (pointer: fine)
• All motion must respect prefers-reduced-motion
• Breakpoints and the respond-to mixin live in src/_breakpoints.scss; do not invent extra breakpoint names
• Shared glass, layout and focus treatments belong on the global primitives (.glass-surface, .content-container, .stack, .cluster), not copied into component stylesheets
• Keep component styles under the anyComponentStyle budget (4 kB warn, 8 kB error)

Content rules

All user-facing copy comes from the typed bilingual content layer in src/app/core/content. Never inline marketing or page copy in templates.

Keep the four copy roles as separate fields:

• headline — the serious heading
• proof — only a verifiable statement
• playfulLine — optional wordplay; never a capability claim
• cta — action label, kept swappable

German and English are written idiomatically per language, never machine-translated word for word.

Claims policy (non-negotiable)

• No unsupported superlatives
• No invented references, client names, metrics or certifications
• Unproven AI, local-LLM or multi-agent capabilities are phrased as an offering or way of working, never as a delivered reference
• The CV stations HUP, BitWiz and Cybertrading are deliberately excluded from all public pages, cases and timelines
• The legal pages (Impressum, Datenschutz) contain placeholders that MUST be reviewed by the site owner before publication and must visibly say so

i18n rules

• German at /, English under /en
• Primary navigation is Home, Services, Projects, About and Contact. Services is one anchored page with four sections. Stack and Pitch stay reachable from content and the terminal, not from the primary nav.
• Every route id exists in both locales
• New pages are added by extending the route-id table in src/app/core/routing, never by hard-coding paths
• Do not swap LOCALE_ID; the active locale is AppLocale from LocaleService

SSR rules

• No window, document, navigator, localStorage or matchMedia access outside afterNextRender or isPlatformBrowser guards
• Use the injected DOCUMENT token when the document element is required (it works on server and browser)
• No user-agent sniffing; use CSS media queries for device capability
• Exception: isApplePlatform() in src/app/core/platform/browser.ts may read navigator.userAgentData?.platform ?? navigator.platform after hydration, only to label the Command key. There is no CSS media query for that key. It is not used for device capability.
• Capability helpers live in src/app/core/platform/browser.ts and return conservative defaults on the server
• Helpers that use inject() must be called from a field initializer or constructor, never from a lifecycle hook or callback, and the resolved value must be stored on the instance
• Every addressable route must remain prerenderable

Accessibility checklist

• Skip link as the first focusable element, targeting #main-content
• Single h1 per page
• Landmark elements (header/nav, main, footer)
• Visible :focus-visible ring
• Keyboard reachability for every action
• aria-current on the active nav item
• At least 4.5:1 text contrast on the base surface
• Reduced-motion alternatives for animation and smooth scrolling
• Navigation remains usable in its server-rendered default state (no JS-only menus)

SEO expectations

• Semantic headings
• Real locale-prefixed URLs
• Server-rendered core text
• Per-route titles from the content layer
• Canonical origin is SITE_CONFIG.siteOrigin (https://antoniolede.de); every absolute URL in the app and tests is derived from it
• Per-route metadata (description, canonical, reciprocal hreflang including x-default, Open Graph, Twitter, robots) is written by SeoService during SSR and on every client navigation
• One JSON-LD @graph script per route: Person and ProfessionalService on Home, one Service entry per services section on the services route, CreativeWork per public case on projects, WebPage elsewhere
• public/robots.txt, public/sitemap.xml and public/llms.txt stay synchronized with prerenderablePaths() via crawl-assets.spec.ts
• The language switch exposes hreflang on the alternate-locale link

Browser binaries, HTML reports, traces and screenshots are not committed (test-results, playwright-report, .lighthouseci).

Test checklist

A change is not done until:

1. npm run lint exits 0
2. npm run format:check exits 0
3. npm run test:ci exits 0 with no watcher left running
4. npm run build exits 0
5. New or changed routes appear in prerenderablePaths() and are prerendered
6. Routing and locale contracts still have unit coverage (paths, locale helpers, navigation links)
7. No new window / document / navigator reads were added outside an SSR-safe guard
8. Placeholder or legal copy was not replaced with invented professional claims
9. Crawl files still match SITE_CONFIG.siteOrigin and prerenderablePaths()
10. Playwright (npm run e2e) and Lighthouse CI (npm run lighthouse) still pass when the change affects public HTML, metadata or chrome

Domain boundaries

Branch	Owns
Foundation	Tooling, tokens, shell, routing and content contracts, SSR safety, test baseline
Content	Bilingual copy data and page composition
Signature	Systems Map, terminal dock, dot background and motion
Integration	SEO and cross-cutting a11y/performance hardening

Each branch extends the shared contracts instead of duplicating paths or copy. The Content branch owns the bilingual copy tree behind SITE_CONTENT. The Signature branch may replace the dot-background internals but must keep the SSR-safe init/teardown contract.