diff --git a/README.md b/README.md
index fa7faab..d1604d0 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,73 @@
 # WebComponents
 
-Technical Specification: Native Profile Form Editor
+Native full-stack demo app "Profile editor" built with plain Node.js, browser ES modules, Web Components, Shadow DOM, templates, and shared domain logic.
 
-## 1. Goal
+Technical specification and reference for a small application that browses, searches, creates, edits, and deletes professional profiles. The application demonstrates a frontend without frameworks, bundlers, client-side template fetching, or duplicated business rules.
 
-Develop a small full-stack application for browsing, searching, creating, editing and deleting user profiles.
+The main idea is to keep application behavior in a shared domain module and run the same rules on both sides. The application is not a simple CRUD form.
 
-The application must load profile data from:
+It supports:
 
-```text
-GET http://127.0.0.1/profile/{username}
+- profile directory
+- profile search
+- profile creation
+- profile editing
+- profile deletion
+- client-side validation
+- server-side validation
+- computed profile fields
+- shared domain logic for browser and server
+
+## Design constraints
+
+- The project avoids direct fetch calls from components
+- Use only native APIs
+- Do not use runtime npm dependencies
+- Use plain Node.js on the server
+- Use browser ES modules on the client
+- Use Web Components, Template API, and Navigation API on the client
+- Use `<template>` for UI fragments and Web Components with Shadow DOM where appropriate
+
+Development tools (ESLint, Prettier) are optional and used only at design time.
+
+## Run
+
+Install development dependencies:
+
+```bash
+npm install
 ```
 
-It must render the data in an editable form and save the updated profile back to the same endpoint:
+Start the server:
 
-```text
-POST http://127.0.0.1/profile/{username}
+```bash
+node server.js
 ```
 
-The application must also support profile search with partial input by first name, last name and email.
+Open:
 
-Each profile is identified by a username. The username in the URL must match the profile file name under `./data/profile/` without the `.json` extension. For example, `/profile/marcus` reads and writes `./data/profile/marcus.json`.
+```text
+http://127.0.0.1:8000/
+```
+
+Example profile page:
 
-The project must demonstrate shared domain logic that runs both in the browser and on the server. The application must not be a simple CRUD form.
+```text
+http://127.0.0.1:8000/profile/marcus
+```
 
-## 2. Main Restrictions
+## Scripts
 
-- Use only native APIs.
-- Do not use npm dependencies.
-- Do not use frontend frameworks.
-- Do not use backend frameworks.
-- Do not use bundlers, transpilers, other tooling.
-- Use plain Node.js on the server.
-- Use browser ES modules on the client.
-- Use Web Components, Template API and Navigation API on the client. The Navigation API is intended for managing SPA-style navigations and browser history entries.
-- Use `<template>` for UI fragments and Web Components with Shadow DOM where appropriate. MDN describes `<template>` and `<slot>` as native tools for building reusable Web Component structures.
+```bash
+npm run lint
+npm run fix
+```
 
-## 3. Required Domain Idea
+## Domain model
 
-The profile must contain data that requires real business logic. Use the domain model "Professional Profile".
+Each profile is identified by a username. The username in the URL must match the profile file name under `./data/profile/` without the `.json` extension. For example, `/profile/marcus` reads and writes `./data/profile/marcus.json`.
 
-Example profile for user `marcus`:
+Example profile:
 
 ```json
 {
@@ -61,219 +88,126 @@ Example profile for user `marcus`:
 }
 ```
 
-Shared domain logic must calculate:
-
-```text
-displayName
-age
-seniorityLevel
-monthlyCapacityHours
-estimatedMonthlyIncome
-profileCompleteness
-publicSlug
-validation errors
-normalized profile data
-```
+### Computed fields
 
-Business rules:
+The domain layer calculates:
 
 ```text
 displayName = firstName + " " + lastName
-
-age is calculated from birthDate
-
-seniorityLevel:
-0..1 years = Junior
-2..4 years = Middle
-5..9 years = Senior
-10+ years = Principal
-
+age = calculated from birthDate
+seniorityLevel = Junior | Middle | Senior | Principal (from experienceYears)
 monthlyCapacityHours = weeklyAvailabilityHours * 4
-
 estimatedMonthlyIncome = monthlyCapacityHours * hourlyRate
+profileCompleteness = percentage based on required fields
+publicSlug = normalized public name slug derived from firstName and lastName
+```
 
-profileCompleteness is a percentage based on required fields
-
-publicSlug is derived from firstName and lastName
+### Validation
 
-email must contain "@"
+Validation runs in the browser while editing and on the server before saving.
 
-firstName and lastName are required
+Rules:
 
+```text
+id is required
+id must match safe username pattern
+firstName is required
+lastName is required
+email must contain "@"
+birthDate must be valid and in the past
 experienceYears must be an integer from 0 to 60
-
 weeklyAvailabilityHours must be an integer from 0 to 80
-
 hourlyRate must be a number from 0 to 1000
-
-birthDate must be a valid date in the past
-
 secondarySkills must be an array of non-empty strings
+currency is normalized to uppercase
+email is normalized to lowercase
 ```
 
-The same domain module must run:
-
-- in the browser during form editing
-- on the server before saving data
-
-The server must never trust client-side validation.
-
-## 4. Required User Flow
-
-The app home route (`/`) must show a profile directory page with:
-
-- a search input
-- a profile list
-- create profile action
-- delete profile action for each listed profile
-
-Search behavior:
-
-- search request supports partial input
-- search matches are case-insensitive
-- search must match by `firstName`, `lastName` and `email`
-- UI updates list after each search input change (with debounce up to 300ms allowed)
-- empty search query returns top 10 profiles
-
-Open a profile by username, for example:
-
-```text
-http://127.0.0.1:8000/profile/marcus
-```
-
-The client app must use Navigation API to handle routes like `/profile/{username}`.
-
-The app loads JSON from:
-
-```text
-GET /profile/{username}
-```
-
-The app renders the profile form.
+The server never trusts browser validation.
 
-When the user edits any field, the browser must immediately run the shared domain logic.
+## Shared domain logic
 
-The UI must immediately update:
+The domain model lives in `shared/profile.js`.
 
-```text
-validation messages
-display name
-age
-seniority level
-monthly capacity
-estimated monthly income
-profile completeness
-public slug
-save button state
-```
+It exports: `schema`, `normalize`, `validate`, `calculate`, `buildState`.
 
-When the user clicks Save, the client sends:
+The same module is imported by:
 
 ```text
-POST /profile/{username}
-Content-Type: application/json
-```
-
-Create flow:
-
-- from directory page user can open a create form
-- user enters `id` (username) and profile fields
-- while user fills create form, frontend runs shared domain validation/business logic and shows immediate errors/computed values
-- create submit must stay disabled while local create form state is invalid
-- user submits create action
-- server validates shared domain rules and username uniqueness
-- after successful create, app navigates to `/profile/{username}` or refreshes directory list
-
-Delete flow:
-
-- from directory page user clicks delete action for profile
-- UI asks for confirmation before delete
-- client sends delete request for selected username
-- after successful delete, profile disappears from directory list
-
-The server runs the same domain logic again.
-
-If data is invalid, the server returns:
-
-```json
-{
-  "ok": false,
-  "errors": {
-    "email": "Invalid email"
-  }
-}
-```
-
-If data is valid, the server saves normalized profile data and returns:
-
-```json
-{
-  "ok": true,
-  "profile": {},
-  "computed": {}
-}
+static/components/profile-form.js
+routes/profile.js
+routes/search.js
 ```
 
-## 5. Server Requirements
-
-Use only Node.js core modules:
+This keeps browser behavior and server behavior consistent.
 
-```text
-node:http
-node:fs
-node:path
-node:url
-```
-
-The server must:
-
-- serve static files from `./static`
-- serve shared domain files from `./shared`
-- serve profile JSON from `./data/profile/{username}.json`
-- serve profile directory listing from `./data/profile`
-- support profile search with partial matching by name and email
-- support `GET /profile/{username}` for any existing profile file
-- support `POST /profile/{username}` for any valid username
-- support `PUT /profile/{username}` (optional alias of POST for updates)
-- support `DELETE /profile/{username}` for deleting existing profile files
-- support `GET /search?name={value}&email={value}` returning filtered profile summaries
-- support `PUT /profile` for creating a new profile
-- treat the URL username as the profile file name without the `.json` extension
-- accept only safe username values that can be used as file names
-- return correct `Content-Type`
-- return `404` for unknown routes and missing profile files
-- return `405` for unsupported methods
-- return `400` for invalid JSON
-- return `409` for create requests when username already exists
-- return `422` for domain validation errors
-- return `500` only for unexpected server errors
-- Static files must be read from disk per request.
-- Do not cache static files in memory.
-- Do not use dynamic API module caching.
-- Do not expose files outside the project directory.
-- Prevent path traversal.
-
-### Server Routing
-
-The request dispatcher must be implemented as a **collection of route handlers**, not as a chain of `if/else` or `switch` statements in `server.js`. At startup the server scans `routes/` and builds a routing table that maps the **first URL path segment** to a route module. The dispatcher looks up that segment and delegates the request.
-
-Route modules are plain `.js` files. Each module exports a default object of HTTP method handlers: `{ GET, POST, PUT, DELETE }`. The router maps the **first URL path segment** to a module file (`search.js` → `/search`, `profile.js` → `/profile/...`). Handler arity defines the expected path shape: a handler `(channel)` serves the mount path (`/search`), a handler `(channel, username)` serves one segment below (`/profile/marcus`).
-
-Suggested route modules:
+## Project structure
 
 ```text
-routes/
-  static.js      static file cache and serving (not a route module)
-  search.js      GET /search?name=&email=
-  profile.js     GET|POST|DELETE /profile/{username}, PUT /profile, PUT /profile/{username}
-```
+.
+├── config.js
+├── server.js
+├── data/
+│   └── profile/
+├── lib/
+│   ├── channel.js
+│   └── router.js
+├── routes/
+│   ├── profile.js
+│   ├── search.js
+│   └── static.js
+├── shared/
+│   ├── profile.js
+│   └── utils.js
+└── static/
+    ├── api.js, app.js
+    ├── index.html, styles.css
+    └── components/
+        ├── <component-name.html>
+        └── <component-name.js>
+```
+
+## Server architecture
+
+The server:
+
+- serves the main page (`index.html` with assembled templates) at `/` and `/index.html`
+- serves static files from `./static` at URL root (`/app.js`, `/styles.css`, `/components/*`, and so on)
+- serves shared domain files from `./shared` under `/shared/*`
+- serves profile JSON from `./data/profile/{username}.json`
+- serves `GET /profile/{username}` with `Accept: text/html` as the main page for browser navigation
+- supports profile search with partial matching by display name and email
+- supports `GET /profile/{username}` with `Accept: application/json` — read profile JSON
+- supports `POST /profile/{username}` — update
+- supports `PUT /profile` — create
+- supports `DELETE /profile/{username}` — delete
+- supports `GET /search?name={value}&email={value}`
+- accepts only safe username values
+- returns correct `Content-Type`
+- returns `404` for unknown routes and missing profile files
+- returns `405` for unsupported methods
+- returns `400` for invalid JSON
+- returns `201` for successful profile creation
+- returns `409` for create requests when username already exists
+- returns `422` for domain validation errors
+- returns `500` only for unexpected server errors
+- does not expose files outside the project directory
+- prevents path traversal
+
+### Server routing
+
+The request dispatcher is implemented as a **collection of route handlers**, not as a chain of `if/else` or `switch` statements.
+
+At startup the server scans `routes/` and builds a routing table that maps the **first URL path segment** to a route module. The dispatcher looks up that segment and delegates the request.
+
+Route modules are plain `.js` files. Each module exports a default object of HTTP method handlers: `{ GET, POST, PUT, DELETE }`. The router maps the **first URL path segment** to a module file (`search.js` to `/search`, `profile.js` to `/profile/...`). Handler arity defines the expected path shape: a handler `(channel)` serves the mount path (`/search`), a handler `(channel, username)` serves one segment below (`/profile/marcus`).
 
 Example: `routes/profile.js` receives requests whose first segment is `profile`:
 
 ```js
 export default {
   GET: getProfile,
-  POST: saveProfile,
+  POST: updateProfile,
   PUT: createProfile,
   DELETE: removeProfile,
 };
@@ -289,76 +223,31 @@ export default {
 
 The router loads modules dynamically with `readdir`. Segment depth and HTTP method dispatch live in the router; route modules contain only named handlers and the method map. `server.js` contains only bootstrap and dispatch.
 
-## 6. Client Requirements
-
-Use only native browser APIs:
-
-- `customElements`
-- `HTMLElement`
-- Shadow DOM
-- `template.content.cloneNode(true)`
-- `fetch`
-- `FormData`
-- `URL`
-- Navigation API
-- ES modules
-
-Client structure must include at least:
-
-```text
-profile-app
-profile-form
-profile-field
-profile-summary
-validation-message
-profile-directory
-profile-search
-profile-list
-profile-item
-profile-create-dialog
-```
-
-- The form must be generated from a template.
-- The app must not use `innerHTML` for untrusted data.
-- Use `textContent`, attributes and DOM methods for dynamic data rendering.
-- The save button must be disabled while the local domain state is invalid.
-- After successful save, show a small saved status.
-- After failed save, show server-side validation errors.
-- Search UI must allow partial query and list matching profiles by name/email.
-- The app must provide UI controls to create profile and delete profile.
-- The create profile UI must run the shared domain module in-browser before submit.
-- Delete action must include a confirmation step before request.
-
-### Network Layer
-
-All `fetch` calls must be encapsulated in a single dedicated module:
-
-```text
-static/api.js
-```
-
-This module exports one async function per server endpoint. Components must never call `fetch` directly. They import and call the API functions from `api.js`.
+## Frontend architecture
 
-```js
-const getProfile = async (username) => { ... };
-const saveProfile = async (username, data) => { ... };
-const deleteProfile = async (username) => { ... };
-const searchProfiles = async ({ name, email } = {}) => { ... };
-const createProfile = async (data) => { ... };
+The frontend is composed from small custom elements.
 
-export { getProfile, saveProfile, deleteProfile, searchProfiles, createProfile };
-```
+- `static/app.js` - application entry point. It imports and registers frontend components.
+- `profile-app` — main page: routing, Navigation API, top-level layout
+- `profile-directory` — directory page: coordinates search, list, create flow
+- `profile-search` — debounced search input, emits `search-change` event
+- `profile-list` — renders a list of profile summaries from a data property
+- `profile-item` — renders one summary row, emits `open-profile` / `delete-profile`
+- `profile-form` — editable profile form driven by state; submits via `api.js`
+- `profile-field` — single labeled field with validation message display
+- `profile-summary` — displays read-only computed fields
+- `validation-message` — displays one error string
+- `profile-create-dialog` — modal wrapper for the create flow (present but unused in current flow)
 
-Each function returns a normalized result object. HTTP error handling, JSON parsing and status checks happen inside `api.js`, not in components.
+Components do not perform network requests inline. They call the API facade from `api.js` or receive data through properties and events.
 
-### Template Strategy
+### Templates
 
-Each component's Shadow DOM markup lives in a dedicated `.html` file co-located with its `.js` file:
+Each visual component has a separate `.html` file with a single `<template>`, co-located with its `.js` file:
 
 ```text
-static/components/
-  profile-item.js
-  profile-item.html
+static/components/profile-form.html
+static/components/profile-form.js
 ```
 
 The `.html` file contains one `<template>` element with a matching `id`:
@@ -380,7 +269,7 @@ The `.html` file contains one `<template>` element with a matching `id`:
 </template>
 ```
 
-**Server-side assembly.** When the server handles any request that returns `index.html` (the root `/` and all `/profile/:username` browser navigations), it reads `index.html` and all `static/components/*.html` files, concatenates the template fragments, and replaces a placeholder comment in `index.html` before sending the response:
+**Server-side assembly.** At startup, `routes/static.js` reads `index.html` and all `static/components/*.html` files, concatenates the template fragments, replaces a placeholder comment in `index.html`, and caches the assembled document in memory:
 
 ```html
 <!-- index.html -->
@@ -391,9 +280,7 @@ The `.html` file contains one `<template>` element with a matching `id`:
 </body>
 ```
 
-The browser receives a single document that already contains all `<template>` elements. No browser-side fetching, no `DOMParser`, no `async` in component modules.
-
-Components read their template synchronously from the document:
+The browser receives a single document that already contains all `<template>` elements. Components read their template synchronously from the document:
 
 ```js
 class ProfileItem extends HTMLElement {
@@ -407,16 +294,16 @@ class ProfileItem extends HTMLElement {
 }
 ```
 
-This approach combines the best of both worlds: HTML structure stays in co-located `.html` files (pure HTML, editor-friendly, close to the component), while the browser pays zero extra requests and components remain fully synchronous.
+So components do not need: browser-side template fetching, build step, bundler.
 
-### Declarative Rendering
+### Declarative rendering
 
-Components must minimize imperative DOM construction. Follow these guidelines:
+Components minimize imperative DOM construction:
 
-- Use `<slot>` for variable child content instead of injecting children from JavaScript.
-- Drive display updates by setting `textContent` on pre-queried named elements rather than building new nodes.
-- For repeated items (profile list), clone the item template once per data entry and fill named child elements, rather than calling `createElement` and manually building the subtree.
-- For field-to-display mappings (computed fields in `profile-summary`), derive keys from shared metadata:
+- Drive display updates by setting `textContent` or attributes on pre-queried elements rather than rebuilding subtrees.
+- For repeated items, `profile-list` creates one `profile-item` element per summary and fills it through attributes.
+- For form fields, `profile-form` creates one `profile-field` element per schema entry and updates values and errors from domain state.
+- For computed fields, `profile-summary` derives keys from shared metadata:
 
 ```js
 import { schema } from '/shared/profile.js';
@@ -429,103 +316,29 @@ for (const [key, metadata] of Object.entries(schema)) {
 
 Computed fields are declared in `schema` with `computed: true`.
 
-- Avoid `while (el.firstChild) el.removeChild(el.firstChild)`. Prefer `el.replaceChildren()` or reset a container once.
-- Avoid dynamic element type switching at runtime (e.g. swapping `<input>` for `<textarea>`). Declare both in the template and show/hide with CSS via an attribute on the host.
-
-### Component Responsibilities
-
-Each component has one clear responsibility:
-
-| Component               | Responsibility                                                           |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `profile-app`           | SPA shell: routing, Navigation API, top-level layout                     |
-| `profile-directory`     | Directory page: coordinates search, list, create dialog                  |
-| `profile-search`        | Debounced search input, emits `search-change` event                      |
-| `profile-list`          | Renders a list of profile summaries from a data property                 |
-| `profile-item`          | Renders one summary row, emits `open-profile` / `delete-profile`         |
-| `profile-form`          | Editable profile form driven by state; delegates saves via events or API |
-| `profile-field`         | Single labeled field with validation message display                     |
-| `profile-summary`       | Displays read-only computed fields                                       |
-| `validation-message`    | Displays one error string                                                |
-| `profile-create-dialog` | Modal wrapper for the create flow                                        |
-
-Components do not perform network requests inline. They call the API facade from `api.js` or receive data through properties and events.
-
-## 7. Shared Domain Module
+- Prefer `replaceChildren()` over manual child removal loops.
+- `profile-field` declares both `<input>` and `<textarea>` in the template and shows one of them with CSS.
+- Do not use `innerHTML` for untrusted data. Use `textContent`, attributes, and DOM methods.
 
-Create one shared module used by both client and server:
+## API client
 
-```text
-/shared/profile.js
-```
+All frontend network calls are isolated in `static/api.js`.
 
-It must export pure functions:
+It exports: `getProfile`, `saveProfile`, `deleteProfile`, `searchProfiles`, `createProfile`.
 
-```js
-const normalize = (profile) => {
-  // returns new normalized object
-};
+Each function returns a normalized result object. HTTP error handling, JSON parsing, and status checks happen inside `api.js`, not in components. Components do not call `fetch` directly.
 
-const validate = (profile, now = new Date()) => {
-  // returns errors object when invalid
-};
+## HTTP API
 
-const calculate = (profile, now = new Date()) => {
-  // returns computed fields
-};
+Profile routes use a dynamic username segment. The username must match the file name in `./data/profile/` without the `.json` extension.
 
-const buildState = (profile, now = new Date()) => {
-  // returns { profile, computed, errors? }
-};
+### Search profiles
 
-export { normalize, validate, calculate, buildState };
+```http
+GET /search?name={value}&email={value}
 ```
 
-- Functions must not mutate arguments.
-- Functions must not access DOM.
-- Functions must not access files.
-- Functions must not use global mutable state.
-- Functions must be deterministic except for the explicitly passed `now`.
-
-## 8. Suggested Project Structure
-
-```text
-server.js                   entry point: bootstrap + dispatch
-routes/
-  static.js                 static file cache and serving
-  search.js                 GET /search?name=&email=
-  profile.js                GET|POST|DELETE /profile/{username}, PUT /profile
-shared/
-  profile.js                 shared domain: normalize, validate, calculate
-data/
-  profile/
-    marcus.json
-    faustina.json
-static/
-  index.html                SPA shell (minimal, no embedded templates)
-  app.js                   imports and registers all components
-  api.js                   network facade (all fetch calls live here)
-  styles.css
-  components/
-    profile-app.js         + profile-app.html
-    profile-form.js        + profile-form.html
-    profile-field.js       + profile-field.html
-    profile-summary.js     + profile-summary.html
-    validation-message.js  + validation-message.html
-    profile-directory.js   + profile-directory.html
-    profile-search.js      + profile-search.html
-    profile-list.js
-    profile-item.js        + profile-item.html
-    profile-create-dialog.js + profile-create-dialog.html
-```
-
-## 9. API Contract
-
-Profile routes use a dynamic username segment. The username must match the file name in `./data/profile/` without the `.json` extension.
-
-GET `/search?name={value}&email={value}`
-
-Success response:
+Response:
 
 ```json
 {
@@ -542,92 +355,110 @@ Success response:
 
 Notes:
 
-- `name` is optional
-- `email` is optional
+- `name` and `email` are optional
+- empty filters return all profiles
 - search is case-insensitive
-- `name` supports partial matches against `firstName`, `lastName` and `displayName`
+- results are sorted by username
+- `name` supports partial matches against computed `displayName`
 - `email` supports partial matches against `email`
 
-PUT `/profile`
+### Get profile
+
+```http
+GET /profile/{username}
+Accept: application/json
+```
+
+Browser navigation with `Accept: text/html` returns the main page (`index.html`) instead of JSON.
 
-Request body:
+JSON response:
 
 ```json
 {
-  "id": "new-user",
-  "firstName": "New",
-  "lastName": "User",
-  "email": "new.user@example.com"
+  "ok": true,
+  "profile": { "...": "normalized profile fields" },
+  "computed": { "...": "calculated fields" }
 }
 ```
 
-Success response:
+### Save profile
+
+```http
+POST /profile/{username}
+Content-Type: application/json
+```
+
+Response:
 
 ```json
 {
   "ok": true,
-  "profile": {},
-  "computed": {}
+  "profile": { "...": "normalized profile fields" },
+  "computed": { "...": "calculated fields" }
 }
 ```
 
-Conflict response (id already exists):
+Validation error (`422`):
 
 ```json
 {
   "ok": false,
-  "errors": { "id": "Profile already exists" }
+  "profile": { "...": "normalized profile fields" },
+  "computed": { "...": "calculated fields" },
+  "errors": {
+    "email": "Invalid email"
+  }
 }
 ```
 
-GET `/profile/{username}`
+### Create profile
 
-Success response:
-
-```json
-{
-  "ok": true,
-  "profile": {},
-  "computed": {}
-}
+```http
+PUT /profile
+Content-Type: application/json
 ```
 
-POST `/profile/{username}`
-
-Request body:
+Success response (`201`):
 
 ```json
 {
-  "firstName": "Marcus",
-  "lastName": "Aurelius",
-  "email": "marcus@example.com"
+  "ok": true,
+  "profile": { "...": "normalized profile fields" },
+  "computed": { "...": "calculated fields" }
 }
 ```
 
-Success response:
+Validation error (`422`):
 
 ```json
 {
-  "ok": true,
-  "profile": {},
-  "computed": {}
+  "ok": false,
+  "profile": { "...": "normalized profile fields" },
+  "computed": { "...": "calculated fields" },
+  "errors": {
+    "email": "Invalid email"
+  }
 }
 ```
 
-Validation error response:
+Conflict response (`409`):
 
 ```json
 {
   "ok": false,
-  "profile": {},
-  "computed": {},
-  "errors": { "email": "Invalid email" }
+  "errors": {
+    "id": "Profile already exists"
+  }
 }
 ```
 
-DELETE `/profile/{username}`
+### Delete profile
+
+```http
+DELETE /profile/{username}
+```
 
-Success response:
+Response:
 
 ```json
 {
@@ -635,42 +466,113 @@ Success response:
 }
 ```
 
-## 10. Acceptance Criteria
+## Routes
 
-The app starts with:
+Client routes handled by `profile-app` with the Navigation API:
 
-```bash
-node server.js
+```text
+/                  profile directory
+/new               create profile
+/profile/:username edit profile
 ```
 
-The browser opens a profile form by username, for example:
+Server routes:
 
 ```text
-http://127.0.0.1:8000/profile/marcus
+GET    /                         main page
+GET    /index.html               main page
+GET    /profile/:username        JSON profile or main page (depends on Accept)
+POST   /profile/:username        update profile
+PUT    /profile                  create profile
+DELETE /profile/:username        delete profile
+GET    /search                   search profiles
+GET    /shared/*                 shared domain modules
+GET    /app.js, /styles.css, /components/*, and other static files
+```
+
+`/new` is a client-side route only. A direct server request to `/new` is not handled and returns `404`. Open the create flow from `/` or navigate in-app after the main page has loaded.
+
+`GET /profile/{username}` serves the main page when the browser sends `Accept: text/html`, which makes full-page navigation to profile URLs work.
+
+## Data storage
+
+Profiles are stored as JSON files:
+
+```text
+data/profile/{username}.json
 ```
 
-- The initial form data is loaded from the server for the requested username.
-- The home route shows a profile directory with search, create and delete controls.
-- Search supports partial input and finds profiles by name or email.
-- Editing the form immediately recalculates computed fields.
-- Invalid fields immediately show validation errors.
+The URL username maps to the file name. Only safe usernames are accepted.
+
+Example:
+
+```text
+/profile/marcus - data/profile/marcus.json
+```
+
+## User flows
+
+### Directory
+
+1. Open `/`.
+2. App renders profile directory with search, create, and delete controls.
+3. Directory loads profiles through `/search`.
+4. User searches by display name or email (partial, case-insensitive).
+5. Matching profiles are rendered as list items after each input change (250 ms debounce).
+
+### Edit
+
+1. Open `/profile/marcus`.
+2. App loads profile JSON from `GET /profile/marcus`.
+3. Form renders editable fields.
+4. Each field change rebuilds domain state.
+5. Computed values, validation messages, and save button state update immediately.
+6. Save sends `POST /profile/marcus`.
+7. Server validates with the same domain module.
+8. Server saves normalized profile JSON on success.
+
+### Create
+
+1. From `/`, click Create, or navigate in-app to `/new`.
+2. App renders `profile-form` in create mode (username field is editable).
+3. Domain state is recalculated on every edit; invalid form disables submit.
+4. Submit sends `PUT /profile`.
+5. Server validates domain rules and username uniqueness.
+6. Successful creation navigates to `/profile/{username}`.
+
+### Delete
+
+1. Open `/`.
+2. Click delete on a profile item.
+3. Browser asks for confirmation.
+4. Client sends `DELETE /profile/{username}`.
+5. Directory reloads after successful deletion.
+
+## Security
+
+The implementation avoids rendering untrusted data with `innerHTML`. Dynamic values are rendered with `textContent`, attributes, and DOM methods.
+
+The server validates usernames before mapping them to file paths. The router prevents path traversal when serving static and shared files.
+
+## Acceptance criteria
+
+- The app starts with `node server.js`.
+- The home route shows a profile directory with search, create, and delete controls.
+- Search supports partial input and finds profiles by display name or email.
+- Opening `/profile/marcus` loads the profile from the server.
+- Editing the form immediately recalculates computed fields and validation errors.
 - The save button is disabled when the profile is invalid.
-- POST sends JSON to the same endpoint.
-- Creating a profile stores new valid data under `./data/profile/{username}.json`.
-- Deleting a profile removes `./data/profile/{username}.json`.
-- The server validates the data using the same shared domain module.
-- Invalid POST data is not saved.
-- Valid POST data is normalized and saved to `./data/profile/{username}.json`.
-- Refreshing the page shows the last saved valid data for the same username.
-- No npm dependencies are installed.
-- No framework or bundler is used.
-- The implementation remains small and readable.
+- POST sends JSON to the same endpoint; the server validates with the shared domain module.
+- Invalid data is not saved; valid data is normalized and saved to `./data/profile/{username}.json`.
+- Creating a profile stores new valid data; deleting removes the profile file.
+- Refreshing the page shows the last saved valid data.
+- No runtime framework or bundler is used.
 - All `fetch` calls are in `static/api.js` only.
-- The server routing table maps the first URL segment to a route module loaded from `routes/`; `server.js` is not a chain of `if/else`.
-- All `<template>` elements are declared in `index.html`; component `.js` files contain no template strings.
-- Components contain no inline `fetch` calls and no raw DOM construction loops.
+- The server routing table maps the first URL segment to a route module from `routes/`.
+- Component templates are assembled into `index.html` server-side; components access them synchronously.
+- Components contain no inline `fetch` calls.
 
-## 11. Non-Goals
+## Non-goals
 
 - Do not implement authentication.
 - Do not implement a database.
@@ -678,3 +580,29 @@ http://127.0.0.1:8000/profile/marcus
 - Do not implement a design system.
 - Do not implement offline mode.
 - Do not implement optimistic conflict resolution.
+
+## Implementation notes
+
+`profile-create-dialog` exists in the component directory, but the current app flow renders `profile-form` directly on `/new`.
+
+`routes/static.js` assembles templates into `index.html` at startup and caches loaded static files in memory.
+
+Search currently returns all matching profiles sorted by username.
+
+`profile-form` stores generated field elements in a `Map` and updates them from domain state.
+
+`profile-summary` receives computed data through a serialized `values` attribute.
+
+## Architectural goal
+
+The frontend is not a CRUD form with scattered validation. The important part is the separation between:
+
+```text
+UI components
+API boundary
+shared domain logic
+server routes
+file storage
+```
+
+The browser gives immediate feedback, but the server remains the final authority.