docs(principles): high-level behavioural guidance + cross-links

.cursor/rules/principles.mdc

@@ -19,29 +19,12 @@ alwaysApply: true
     • HOW  ▸ Abbreviated bullets; see docs/system_principles.md
 -->
 
-# Principles Snapshot
+## Behavioural Principles (micro-summary)
 
-Human Flow & Dignity
-- Human-first agency: auto-apply within band; no accept gesture; no expansion.
-- Flow & rhythm: micro-corrections; defer heavy work during bursts.
-- Low cognitive load: no suggestion lists; subtle underline/highlight; debug opt-in.
-- Accessibility: respect reduced motion; SR announces; keyboard-first.
+- Human: preserve authorship and momentum; keep the surface calm; accessible by default.
+- Safety & trust: caret‑safe; private by default; explain choices simply; fail soft.
+- Logic: smallest context; plain outputs; one thing at a time; validate a small band.
+- Performance: match the device; ship only what we can test.
 
-Safety, Trust & Integrity
-- Caret-safe, non-undoing: never edit at/after caret; band-only; no undo entries.
-- Local-first privacy: prefer local; remote off unless opted in; degrade gracefully; no text persistence.
-- Explainability: show reasons, tiers, and truncations; toggleable explainers.
-- Fail-soft: LM errors → rules-only; single-flight + abort; drop stale.
-
-Adaptive Intelligence & Execution
-- Context-minimal: smallest window; allow control JSON; outputs sanitized & clamped.
-- Single-flight orchestration: one active gen per band; abort on input.
-- Device-tier progressive: detect capabilities → tune cadence/tokens.
-- Testable/observable: gates must pass; logs for merges/aborts/tiers.
-
-Collaboration & Delivery
-- Plan order & Questions: execute tasks in plan order; capture clarifications in `docs/questions.md`.
-- Green gates: typecheck/lint/format/test must pass before merge.
-
-See `docs/system_principles.md` for behaviours and examples.
+See `docs/system_principles.md` for links to deeper docs.
 

docs/system_principles.md

@@ -22,9 +22,131 @@ Elevate human nature and human–machine input. The system amplifies
 clarity, rhythm, and agency while remaining safe, private, and
 explainable.
 
-## Subcategories and Principles
+## Behavioural Principles (high-level)
 
-### A) Human Flow & Dignity
+These are the agent’s ground rules for how to behave in any task. Each
+principle links to deeper docs that hold the technical details.
+
+### Human
+
+1. Preserve authorship and momentum
+
+- Guidance: Keep the person in flow. Apply small, safe fixes without
+  asking; never change what they’re actively typing.
+- Examples:
+  - While the person types, hold back; when they pause, tidy what was
+    written without moving the caret.
+  - If they resume typing, drop any pending idea silently.
+- See also: [PRD](../PRD.md), [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md), [Band policy](guide/reference/band-policy.md), [Acceptance: caret safety](qa/acceptance/caret_safety.feature)
+
+2. Keep the surface calm
+
+- Guidance: No suggestion lists. Use subtle underline/highlight to show
+  what changed; keep UI quiet.
+- Examples:
+  - Fix a comma and briefly underline it; no popups.
+  - Show debug only when explicitly opened.
+- See also: [PRD](../PRD.md), [Voice & tone](../brand/specs/voice-tone.md), [Config flags](guide/reference/config-flags.md), [Web demo details](guide/how-to/web-demo-details.md)
+
+3. Accessible by default
+
+- Guidance: Respect reduced motion and assistive tech; never rely on
+  color or animation alone.
+- Examples:
+  - Replace animations with static highlights if the system asks for
+    less motion.
+  - Announce state changes using OS-standard phrasing.
+- See also: [A11y checklist](a11y/wcag-checklist.md), [PRD](../PRD.md)
+
+### Safety & Trust
+
+4. Caret-safe, never risky
+
+- Guidance: Only touch a small neighborhood behind the caret; never
+  write at/after the caret.
+- Examples:
+  - Correct a misspelling a few words back; do not extend text forward.
+  - If a change would cross the caret, skip it.
+- See also: [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md), [Band policy](guide/reference/band-policy.md), [Acceptance: caret safety](qa/acceptance/caret_safety.feature)
+
+5. Private by default
+
+- Guidance: Prefer local. Remote is opt‑in per session. Do not persist
+  user text.
+- Examples:
+  - If local assets are missing, operate in safe rules‑only mode and
+    nudge setup, not cloud fallback.
+  - Clear the opt‑in when the session ends.
+- See also: [PRD](../PRD.md), [LM behavior](guide/reference/lm-behavior.md), [Config flags](guide/reference/config-flags.md), [Acceptance: local LM](qa/acceptance/local_lm_integration.feature)
+
+6. Explain choices simply
+
+- Guidance: When asked, say what changed and why, without exposing user
+  content.
+- Examples:
+  - “Shortened to fit the safe band.”
+  - “Dropped result because you kept typing.”
+- See also: [Web demo details](guide/how-to/web-demo-details.md), [Implementation](../implementation.md)
+
+7. Fail soft, never block
+
+- Guidance: On any error, step down to a safe mode and keep the person
+  typing.
+- Examples:
+  - Timeouts cancel work and defer until the next pause.
+  - No GPU? Use a simpler path, just slower—not broken.
+- See also: [Architecture constraints (ADR)](../adr/0003-architecture-constraints.md), [Acceptance: streamed diffusion](qa/acceptance/streamed_diffusion.feature)
+
+### Logic & Clarity
+
+8. Smallest context; plain outputs
+
+- Guidance: Use only what’s needed; return clear text, no boilerplate.
+- Examples:
+  - Consider nearby text rather than the whole document.
+  - Strip any labels or wrappers from model output.
+- See also: [LM behavior](guide/reference/lm-behavior.md), [Injector](guide/reference/injector.md)
+
+9. One thing at a time
+
+- Guidance: Don’t juggle. If new input arrives, stop what you were
+  doing.
+- Examples:
+  - Abort a running idea as soon as a new key is pressed.
+  - Ignore late results from an older state.
+- See also: [Architecture: containers](architecture/C2-containers.md), [Implementation](../implementation.md)
+
+10. Check a small neighborhood (validation band)
+
+- Guidance: Validate and correct a short span around the cursor—not the
+  world.
+- Examples:
+  - Fix “teh quick” to “the quick,” but don’t rewrite the sentence.
+  - Leave longer rephrasing to deliberate user actions.
+- See also: [Band policy](guide/reference/band-policy.md), [Caret-safe diff (ADR)](../adr/0002-caret-safe-diff.md)
+
+### Performance & Reliability
+
+11. Meet the device where it is
+
+- Guidance: Use effort that suits the hardware; prioritize responsiveness.
+- Examples:
+  - On fast devices, respond more quickly; on slower ones, take lighter
+    steps.
+  - Warm up once; avoid stutter during typing.
+- See also: [Config flags](guide/reference/config-flags.md), [Web demo details](guide/how-to/web-demo-details.md)
+
+12. Ship only what we can test
+
+- Guidance: Behaviour must be observable and verifiable.
+- Examples:
+  - Add or update tests when rules change.
+  - Keep acceptance criteria green before merging.
+- See also: [QA index](qa/README.md), [Acceptance suite](qa/acceptance), [Implementation](../implementation.md)
+
+## Appendix: Technical mapping
+
+### A) Human Flow & Dignity (detailed)
 
 1. Human-first agency
 
@@ -76,7 +198,7 @@ explainable.
   - Use OS-standard phrasing in screen reader announcements via
     `liveRegion`; ensure all actions are reachable by keyboard.
 
-### B) Safety, Trust & Integrity
+### B) Safety, Trust & Integrity (detailed)
 
 5. Caret-safe, non-undoing edits
 
@@ -104,7 +226,7 @@ explainable.
 
 - Behaviour: Make decisions legible. Log what was proposed, why it was
   accepted/rejected, and the current device tier. Capture uncertainties
-  in `docs/questions.md` and proceed on safe defaults.
+  in `docs/questionnaire/questions.md` and proceed on safe defaults.
 - Examples:
   - In DebugPanel, show: model tier, tokens requested, band size, and
     reason codes (e.g., "caret-entered", "stale-result"); avoid showing raw user text.
@@ -121,7 +243,7 @@ explainable.
   - If WebGPU is unavailable, switch to WASM SIMD/threads and reduce
     max tokens per call.
 
-### C) Adaptive Intelligence & Execution
+### C) Adaptive Intelligence & Execution (detailed)
 
 9. Context-grounded minimality