feat(ux): add onboarding, contractiles, and UX infrastructure

- Purge hardcoded absolute paths (replaced with env vars / relative)
- Add QUICKSTART-USER.adoc with real build/run instructions
- Add doctor/heal/tour/help-me recipes to Justfile
- Add LLM warmup scripts (user + dev, token-efficient)
- Add contractile baselines: MUST, TRUST, INTENT, ADJUST
- Add guix.scm + flake.nix for reproducible environments
- Slim/create AI manifest with tiered context loading

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.machine_readable/ADJUST.contractile

@@ -0,0 +1,112 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; ADJUST.contractile — Accessibility invariants for verisimdb
+; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology
+;
+; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST
+; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants.
+
+; ── Definitions ──────────────────────────────────────────────────
+;
+; ADJUST (noun/verb)
+;   The accessibility contractile. Defines how software must adapt to serve
+;   all users regardless of ability, device, or context. Named for the verb
+;   "adjust" — to make suitable, to adapt, to accommodate — which is the
+;   core action of accessible design.
+;
+; Scope:
+;   ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile,
+;   documentation, error messages, and installation flows. It applies to
+;   both human users and assistive technologies (screen readers, switch
+;   devices, braille displays, voice control).
+;
+; Relationship to other contractiles:
+;   - MUST: ADJUST invariants are a subset of MUST — violating ADJUST
+;     is a MUST violation. ADJUST exists separately because accessibility
+;     rules are numerous enough to warrant their own file, and because
+;     LLMs frequently forget accessibility unless explicitly reminded.
+;   - TRUST: ADJUST does not affect trust levels. All trust tiers must
+;     respect ADJUST invariants equally.
+;   - DUST: Deprecating a feature does not exempt it from ADJUST until
+;     it is fully removed. Deprecated UI must remain accessible.
+;   - INTENT: ADJUST supports the anti-purpose "this software is NOT
+;     only for able-bodied users with modern hardware."
+;
+; Standard: WCAG 2.2 Level AA (minimum)
+;   https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa
+;
+; Why a separate file:
+;   Experience shows LLMs and developers alike treat accessibility as an
+;   afterthought. By placing invariants in a contractile that is loaded
+;   at session start, we make it structurally impossible to forget.
+;
+; ── End Definitions ──────────────────────────────────────────────
+
+(adjust-contractile
+  (version "1.0.0")
+  (full-name "Accessibility & Digital Justice for Universal Software & Technology")
+  (standard "WCAG-2.2-AA")
+  (repo "verisimdb")
+
+  (invariants
+    ; ── Visual ──
+    (adjust "colour-contrast-ratio >= 4.5:1 for normal text")
+    (adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)")
+    (adjust "no information conveyed by colour alone")
+    (adjust "no flashing or strobing content (3 flashes/second max)")
+    (adjust "text resizable to 200% without loss of content or function")
+    (adjust "focus indicators visible on all interactive elements")
+
+    ; ── Keyboard ──
+    (adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)")
+    (adjust "no keyboard traps — user can always Tab away")
+    (adjust "skip navigation link present on pages with repeated blocks")
+    (adjust "logical focus order follows visual reading order")
+
+    ; ── Screen reader ──
+    (adjust "all images have meaningful alt text (or alt='' if decorative)")
+    (adjust "all form inputs have associated labels")
+    (adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)")
+    (adjust "dynamic content updates announced via aria-live regions")
+    (adjust "semantic HTML used (headings, lists, tables) — not div soup")
+
+    ; ── Interactive ──
+    (adjust "touch targets minimum 44x44px on mobile/touch interfaces")
+    (adjust "error messages identify the field and describe the error")
+    (adjust "error messages not conveyed by colour or position alone")
+    (adjust "form validation provides suggestions for correction")
+
+    ; ── Media ──
+    (adjust "video has captions (closed or open)")
+    (adjust "audio-only content has text transcript")
+    (adjust "no autoplay of media with sound")
+
+    ; ── Motion ──
+    (adjust "animations respect prefers-reduced-motion media query")
+    (adjust "no content depends on motion to convey meaning")
+
+    ; ── CLI/TUI ──
+    (adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])")
+    (adjust "TUI must support high-contrast mode")
+    (adjust "all CLI commands support --help with plain-text output")
+    (adjust "error messages written in plain language, not jargon or codes alone")
+
+    ; ── Documentation ──
+    (adjust "docs use clear language, short sentences, logical structure")
+    (adjust "code examples include comments explaining non-obvious steps")
+    (adjust "diagrams have text descriptions or alt text")
+  )
+
+  (enforcement
+    (ci "accessibility linting in quality.yml workflow")
+    (pr-block "PR blocked if accessibility regression detected")
+    (tool "axe-core or pa11y for automated checks on web UI")
+    (tool "CLI output inspected for colour-only signalling")
+    (manual "manual screen reader test before major releases")
+  )
+
+  (notes
+    "These are MINIMUM requirements. Exceeding them (AAA) is encouraged."
+    "When in doubt about an accessibility decision, ask — don't guess."
+    "Accessibility is not optional polish — it is a structural requirement."
+  )
+)

.machine_readable/INTENT.contractile

@@ -0,0 +1,59 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; INTENT.contractile — Purpose and scope for verisimdb
+; Helps LLM/SLM agents understand what this repo IS and IS NOT.
+
+(intent-contractile
+  (version "1.0.0")
+  (repo "verisimdb")
+
+  ; === Purpose (what this repo IS) ===
+  (purpose
+    "VeriSimDB (Veridical Simulacrum Database) is a cross-system entity consistency
+     engine with drift detection, self-normalisation, and formally verified queries.
+     Each entity exists simultaneously across 8 modalities — the octad (Graph, Vector,
+     Tensor, Semantic, Document, Temporal, Provenance, Spatial) — with drift detection
+     and automatic consistency maintenance. It operates as a standalone database OR as a
+     heterogeneous federation coordinator over existing databases. Rust core handles
+     modality stores; Elixir/OTP orchestrates distributed coordination."
+  )
+
+  ; === Anti-Purpose (what this repo is NOT — prevents scope creep) ===
+  (anti-purpose
+    "VeriSimDB is NOT a general-purpose relational database — it solves cross-modal
+     entity consistency. It is NOT a document store, graph database, or vector database
+     alone — it unifies all 8 modalities. It does NOT store application data in its
+     source repository — each consumer gets its own instance, port, and volume. It is
+     NOT an ORM or query builder — VQL (VeriSim Query Language) is the native interface,
+     not SQL."
+  )
+
+  ; === Key Architectural Decisions That Must Not Be Reversed ===
+  (architectural-invariants
+    "8-modality octad — one entity ID maps to exactly eight synchronized stores"
+    "Drift detection with configurable thresholds and automatic self-normalisation"
+    "Elixir orchestration layer with GenServer-per-entity supervision"
+    "Rust core for performance-critical modality stores"
+    "VQL as the native query interface — not SQL"
+    "Standalone mode AND heterogeneous federation coordinator mode"
+    "Each project gets its own VeriSimDB instance + port + volume"
+    "Design justified at Marr's three levels (computational, algorithmic, implementational)"
+    "HTTP API between Elixir orchestration and Rust core"
+    "Prometheus metrics for observability"
+  )
+
+  ; === Sensitive Areas (if in doubt, ask) ===
+  (ask-before-touching
+    "rust-core/ — modality store implementations; changes affect data integrity"
+    "elixir-orchestration/ — GenServer supervision; incorrect changes cause data loss"
+    "connectors/ — federation interfaces; changes affect external database integration"
+    "src/abi/ — formal verification proofs for query correctness"
+    ".machine_readable/ — checkpoint files, format is specified"
+  )
+
+  ; === Ecosystem Position ===
+  (ecosystem
+    (belongs-to "nextgen-databases (monorepo)")
+    (depends-on ("oxigraph" "tantivy" "idris2" "zig"))
+    (depended-on-by ("hypatia" "panll" "ambientops" "boj-server" "idaptik" "gossamer"))
+  )
+)

.machine_readable/MUST.contractile

@@ -0,0 +1,85 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; MUST.contractile — Baseline invariants for verisimdb
+; These constraints MUST NOT be violated. K9 validators enforce them.
+
+(must-contractile
+  (version "1.0.0")
+  (repo "verisimdb")
+
+  ; === Universal Invariants (apply to ALL repos) ===
+
+  (invariants
+    ; Paths
+    (must "no hardcoded absolute paths (/home/*, /mnt/*, /var/mnt/*)")
+    (must "all paths use env vars, XDG dirs, or relative references")
+
+    ; Language policy
+    (must "no new TypeScript files")
+    (must "no new Python files")
+    (must "no new Go files")
+    (must "no npm/bun/yarn/pnpm dependencies — Deno only")
+
+    ; Dangerous patterns
+    (must "no believe_me (Idris2)")
+    (must "no assert_total (Idris2)")
+    (must "no Admitted (Coq)")
+    (must "no sorry (Lean)")
+    (must "no unsafeCoerce (Haskell)")
+    (must "no Obj.magic (OCaml)")
+    (must "no unsafe {} blocks without safety comment (Rust)")
+
+    ; License
+    (must "SPDX-License-Identifier header on every source file")
+    (must "no removal or modification of LICENSE file")
+
+    ; Structure
+    (must ".machine_readable/ directory preserved")
+    (must "0-AI-MANIFEST.a2ml preserved")
+    (must "no SCM files in repo root — only in .machine_readable/")
+
+    ; CI
+    (must "no removal of CI workflows without explicit approval")
+    (must "all GitHub Actions SHA-pinned")
+
+    ; Code quality
+    (must "tests must not be deleted or weakened")
+    (must "generated code in generated/ directory only")
+    (must "no introduction of OWASP top 10 vulnerabilities")
+
+    ; ABI/FFI (if applicable)
+    (must "no modification of ABI contracts without proof update")
+    (must "no removal of formal verification proofs")
+  )
+
+  ; === Project-Specific Invariants (verisimdb) ===
+
+  (invariants
+    ; Octad entity model
+    (must "8-modality octad (Graph, Vector, Tensor, Semantic, Document, Temporal, Provenance, Spatial) must be preserved")
+    (must "one entity ID maps to exactly eight synchronized stores — no modality may be dropped")
+    (must "drift detection must remain active with configurable thresholds")
+    (must "self-normalization triggered by drift events must not be disabled")
+
+    ; Architecture layers
+    (must "Elixir orchestration layer must remain the coordination point (GenServer per entity)")
+    (must "Rust core modality stores must communicate with Elixir via HTTP API")
+    (must "VQL (VeriSim Query Language) must be the query interface — NOT raw SQL")
+
+    ; Data integrity
+    (must "each project gets its own VeriSimDB instance + port + volume — no shared instances")
+    (must "no application data may be stored in the VeriSimDB source repository")
+    (must "Prometheus metrics for observability must remain operational")
+
+    ; Marr's three levels
+    (must "design decisions must be justified at computational, algorithmic, and implementational levels")
+
+    ; Federation
+    (must "standalone mode and heterogeneous federation coordinator mode must both remain functional")
+    (must "connectors/ for external database federation must maintain their interfaces")
+  )
+
+  (enforcement
+    (k9-validator "contractiles/k9/must-check.k9.ncl")
+    (ci "quality.yml runs must-check on every PR")
+  )
+)

.machine_readable/TRUST.contractile

@@ -0,0 +1,45 @@
+; SPDX-License-Identifier: PMPL-1.0-or-later
+; TRUST.contractile — Trust boundaries for verisimdb
+; Defines what LLM/SLM agents are trusted to do without asking.
+
+(trust-contractile
+  (version "1.0.0")
+  (repo "verisimdb")
+
+  (trust-level "maximal")  ; maximal | standard | restricted | minimal
+
+  ; === Maximal Trust (default) ===
+  ; LLM may freely do these without asking:
+  (trust-actions
+    "read"          ; Read any file in the repo
+    "build"         ; Run build commands
+    "test"          ; Run test suites
+    "lint"          ; Run linters and formatters
+    "format"        ; Auto-format code
+    "doctor"        ; Run self-diagnostics
+    "heal"          ; Attempt automatic repair
+    "git-status"    ; Check git status
+    "git-diff"      ; View diffs
+    "git-log"       ; View history
+  )
+
+  ; === Denied Actions (always require human approval) ===
+  (trust-deny
+    "delete-branch"           ; Could lose work
+    "force-push"              ; Overwrites history
+    "modify-ci-secrets"       ; Security sensitive
+    "publish"                 ; External visibility
+    "push-to-main"            ; Protected branch
+    "delete-files-bulk"       ; More than 5 files at once
+    "modify-license"          ; Legal implications
+    "modify-security-policy"  ; Security implications
+    "remove-proofs"           ; Formal verification regression
+    "disable-ci-checks"       ; Safety regression
+    "drop-modality"           ; Removing any of the 8 octad modalities
+    "disable-drift-detection" ; Turning off cross-modal consistency checks
+    "store-app-data"          ; No application data in the VeriSimDB source repo
+  )
+
+  ; === Trust Boundary ===
+  (trust-boundary "repo")  ; LLM confined to this repo unless explicitly told otherwise
+)