diff --git a/.claude/architecture-guardrails.md b/.claude/architecture-guardrails.md
new file mode 100644
index 0000000..abd9c92
--- /dev/null
+++ b/.claude/architecture-guardrails.md
@@ -0,0 +1,77 @@
+# Architecture Guardrails
+
+## Hard boundary for UX tasks
+
+When a task is described as UI, UX, layout, styling, loading feedback or
+presentation work, do not modify:
+
+- reasoning algorithms;
+- unknown selection;
+- reasoning-pattern selection;
+- question formulation;
+- atomicity or answerability assessment;
+- graph mutation;
+- graph schemas;
+- API request or response contracts;
+- reconstruction prompts;
+- provider configuration;
+- confidence propagation;
+- compatibility validation.
+
+If a UX request appears to require one of those changes, stop and report the
+dependency rather than changing it silently.
+
+## Reasoning invariants
+
+Preserve these invariants:
+
+- The LLM proposes information; deterministic code owns graph mutation.
+- Every user-facing question comes from an explicit unresolved graph node.
+- Questions contain one primary concept and seek one coherent answer.
+- Unknowns must be atomic or decomposed.
+- Atomic wording alone is insufficient; a selected unknown must be independently
+  answerable.
+- Question family must match the active reasoning pattern.
+- Active investigation nodes must be compatible with the reasoning pattern.
+- Relationship classification cannot outrun comparability assessment.
+- Ambiguity remains explicit rather than being resolved alphabetically.
+- Parent unknowns do not resolve before their completion rule is satisfied.
+- Confidence must not outrun evidence or completeness.
+- Duplicate evidence must not increase confidence.
+- Conflicting evidence caps conclusion confidence.
+- A successful update must rerun deterministic next-question selection when
+  eligible unknowns remain.
+- No question is preferable to an unjustified question.
+
+## Current architecture, simplified
+
+Scenario
+→ reconstruction
+→ situation graph
+→ unknown selection
+→ atomicity
+→ answerability
+→ reasoning pattern
+→ investigation strategy
+→ question family
+→ question formulation
+→ complexity validation
+→ user answer
+→ proposed graph update
+→ deterministic validation/application
+→ propagation
+→ confidence/completeness update
+→ next unknown
+
+## Compatibility discipline
+
+Do not expand schemas merely because a model emits a synonym.
+
+Prefer:
+
+1. identify the source;
+2. determine whether it is a synonym;
+3. normalise deterministically when justified;
+4. retain strict validation.
+
+Do not weaken validation globally to fix a single malformed response.
diff --git a/.claude/project-context.md b/.claude/project-context.md
new file mode 100644
index 0000000..ecf2c41
--- /dev/null
+++ b/.claude/project-context.md
@@ -0,0 +1,74 @@
+# Project Context
+
+## What the Confidence Engine is
+
+The Confidence Engine is a structured reasoning tool intended to help people
+decide whether they have enough justified confidence to act.
+
+It does not simply answer the user's original question.
+
+It:
+
+1. reconstructs the situation;
+2. separates observations, assumptions, relationships and unknowns;
+3. creates a structured reasoning graph;
+4. selects the most useful unresolved uncertainty;
+5. asks one simple question;
+6. updates the graph from the answer;
+7. repeats until action is justified or the remaining uncertainty is clear.
+
+A chatbot remembers the conversation.
+
+The Confidence Engine preserves the state of the reasoning.
+
+## Product direction
+
+The eventual product should feel like a calm, capable investigator helping the
+user think one step at a time.
+
+The user should not need to understand:
+
+- graph theory;
+- node IDs;
+- internal enums;
+- schemas;
+- prompt versions;
+- proposal validation;
+- model-provider details.
+
+Those remain available through developer/debug views.
+
+## Core product promise
+
+The engine should help a user reach one of these states:
+
+- I have enough justified confidence to act.
+- I do not yet have enough confidence, but I know what to investigate next.
+- I have discovered that my original question needs reframing.
+
+## Current development stage
+
+The deterministic reasoning architecture reached a stable alpha checkpoint.
+
+Current work is primarily improving:
+
+- usability;
+- presentation;
+- loading feedback;
+- plain-language explanations;
+- separation of user and developer views.
+
+Do not resume broad reasoning architecture work unless a repeated observed
+failure clearly requires it.
+
+## Important philosophy
+
+Complicated situations are made from smaller parts.
+
+Each part may influence the whole, but parts do not necessarily carry equal
+weight.
+
+Previous cases may suggest where to investigate, but they must never determine
+the outcome of a new case.
+
+Every case begins with no accepted evidence from previous cases.
diff --git a/.claude/ux-guidelines.md b/.claude/ux-guidelines.md
new file mode 100644
index 0000000..7945343
--- /dev/null
+++ b/.claude/ux-guidelines.md
@@ -0,0 +1,137 @@
+# UX Guidelines
+
+## Main principle
+
+The user should see the next useful step clearly.
+
+The system may retain considerable complexity underneath, but the primary
+workspace should remain calm and understandable.
+
+## Main user view
+
+Prioritise:
+
+1. Your situation
+2. Current understanding
+3. What we are working out
+4. Why it matters
+5. Next question
+6. Answer field
+7. Reasoning progress
+
+## Developer view
+
+Keep technical details behind a collapsed `Developer details` disclosure.
+
+This may contain:
+
+- complete situation graph;
+- graph counts;
+- nodes and edges;
+- affected and resolved nodes;
+- diagnostics;
+- proposal details;
+- raw JSON;
+- prompt and model details;
+- technical confidence data.
+
+Do not remove the developer view. It remains important while the product is
+being tested.
+
+## Language
+
+Use plain language.
+
+Prefer:
+
+- `areas that still need investigation`
+- `what we are working out`
+- `why this matters`
+- `what we understand so far`
+- `next question`
+
+Avoid in the main view:
+
+- unknown nodes;
+- unresolved candidates;
+- activeUnknownNodeId;
+- graph references;
+- proposal compatibility;
+- candidate count;
+- internal enum values;
+- raw IDs.
+
+Never display an unexplained count such as:
+
+`3 remaining`
+
+Explain what the count represents, or omit it.
+
+Do not imply that one unresolved graph node always equals one remaining user
+question.
+
+## Loading experience
+
+Analysis and update requests can take around a minute with the current local
+model.
+
+A disabled button is not sufficient feedback.
+
+Show a visible processing card immediately.
+
+Recommended initial-analysis messages:
+
+- 0–10 seconds: `Reading your situation`
+- 10–25 seconds: `Building a structured understanding`
+- 25–45 seconds: `Identifying what is known and still unclear`
+- 45+ seconds: `Selecting the next useful question`
+
+Recommended update messages:
+
+- 0–10 seconds: `Considering your answer`
+- 10–25 seconds: `Updating the situation`
+- 25–45 seconds: `Checking what changed`
+- 45+ seconds: `Choosing the next question`
+
+These messages are time-based reassurance only.
+
+Do not claim that a backend stage has completed unless the backend explicitly
+reports it.
+
+Show elapsed time.
+
+Do not show fake progress percentages.
+
+Disable duplicate submission while a request is active.
+
+## Visual character
+
+Aim for:
+
+- calm;
+- professional;
+- spacious;
+- accessible;
+- suitable for business, consultancy and government users.
+
+Prefer:
+
+- clear hierarchy;
+- restrained colour;
+- generous whitespace;
+- readable line lengths;
+- consistent cards;
+- accessible contrast;
+- responsive layouts.
+
+Avoid:
+
+- visual clutter;
+- excessive badges;
+- neon colour;
+- unnecessary gradients;
+- glassmorphism;
+- distracting animation;
+- dashboard-style density.
+
+The next question should be the strongest visual element.
diff --git a/.claude/working-rules.md b/.claude/working-rules.md
new file mode 100644
index 0000000..3ac6d2a
--- /dev/null
+++ b/.claude/working-rules.md
@@ -0,0 +1,83 @@
+# Claude Code Working Rules
+
+## Mandatory command constraints
+
+These rules exist because previous long shell commands and streamed responses
+caused tool failures.
+
+- Do not use heredocs.
+- Do not use long `node -e` commands.
+- Do not use long `python -c` commands.
+- If helper code is needed, create a small script file and run it.
+- Keep shell commands short and readable.
+- Break complex work into several commands.
+- Write large outputs to files instead of printing them.
+- Do not print full JSON responses or graph objects.
+- Do not paste complete large files into chat.
+- Prefer: tool → file → concise summary.
+- Keep final reports concise.
+- Do not narrate every implementation step.
+
+## Change discipline
+
+Before editing:
+
+1. state the current branch;
+2. inspect `git status`;
+3. identify the relevant files;
+4. explain the smallest intended change.
+
+Work on one component or concern at a time.
+
+Do not combine unrelated cleanup with the requested task.
+
+Do not reformat unrelated files.
+
+Do not modify production reasoning code during UX tasks.
+
+## Testing discipline
+
+Use focused tests.
+
+Do not run the full test suite unless requested or genuinely necessary.
+
+Do not call Ollama in unit tests.
+
+Do not run live multi-scenario evaluations for ordinary UI changes.
+
+Do not run Playwright unless the task specifically requires it.
+
+Do not weaken existing reasoning tests to make UI changes pass.
+
+## Git discipline
+
+Before committing:
+
+- inspect the diff;
+- confirm no secrets;
+- confirm no internal IP addresses;
+- confirm no raw provider responses;
+- confirm no screenshots;
+- confirm no temporary scripts;
+- confirm no generated test outputs;
+- confirm only intended files changed.
+
+Use a focused commit message.
+
+Do not merge or tag unless explicitly requested.
+
+## Response discipline
+
+At the end of a task, normally report only:
+
+- branch;
+- commit hash, when committed;
+- files changed;
+- behaviour changed;
+- tests;
+- lint/build;
+- manual result, if performed;
+- remaining limitation;
+- git status.
+
+Stop after reporting. Do not begin the next task automatically.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f3ae4c8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,44 @@
+# Confidence Engine
+
+Read these project instructions before making changes:
+
+- @.claude/project-context.md
+- @.claude/architecture-guardrails.md
+- @.claude/ux-guidelines.md
+- @.claude/working-rules.md
+
+## Current working principle
+
+The Confidence Engine helps a person move from uncertainty towards justified
+confidence by asking one simple, useful question at a time.
+
+The graph preserves the state of the reasoning. The conversation is the primary
+user experience.
+
+## Before changing anything
+
+1. Inspect the current branch and working tree.
+2. Read the relevant implementation and tests.
+3. Identify whether the request concerns:
+   - reasoning behaviour;
+   - API/data contracts;
+   - or presentation only.
+4. Respect the boundaries in the imported instructions.
+5. Make the smallest change that satisfies the task.
+
+Do not assume an architectural redesign is wanted.
+
+## Standard validation
+
+For UI-only work, normally run:
+
+```bash
+npm test -- --run tests/ui/scenario-form.test.jsx
+npm run lint
+npm run build
+```
+
+Run additional focused tests only when relevant files are affected.
+
+Do not run Ollama, Playwright, the full test suite, or evaluator suites unless the
+task explicitly requires them.