design(web): separate Obi companion UI from Adrian/admin control surface

[adrianwedd]

Goal

Redesign SPARK's web UI around two distinct users and jobs:

1. Obi / companion surface — simple, safe, relational, age-appropriate interaction with SPARK.
2. Adrian / admin surface — inspect, configure, diagnose, explain, back up, and safely control the system.

The current dashboard grew feature-by-feature and mixes live public telemetry, child interaction, tool controls, projects, and operator concerns. It should now reflect the architecture SPARK actually has: provenance-aware memory, bounded learned preferences, explicit health/liveness, deterministic action gates, GPIO leases, self-evolution via reviewed PRs, and privacy boundaries.

First phase: audit before redesign

Inventory every existing UI panel, route, button, API endpoint, auth boundary, and state field exposed by the web surfaces. Classify each as:

• public/read-only;
• Obi-safe interaction;
• Adrian/admin operation;
• developer/debug only;
• obsolete/redundant;
• privacy-sensitive and currently overexposed.

Do not preserve controls merely because they exist.

Obi surface principles

The Obi UI should feel like interacting with SPARK, not operating Linux or a robotics console.

Prefer:

• conversation and recent shared context;
• "My Projects" / things SPARK and Obi are building together;
• routines/support tools that are actually used;
• understandable learned-preference visibility such as “SPARK has noticed you often choose X after school,” with a simple correction/forget-this path;
• clear quiet/sleep/availability state where useful;
• safe creative/play interactions;
• transparent language about what SPARK knows versus guessed/interpreted;
• minimal controls and low cognitive load.

Avoid:

• raw daemon/service state;
• direct GPIO/motion controls unless part of a deliberately designed activity;
• arbitrary tool invocation;
• model/backend/config choices;
• raw logs, tokens, IPs, filesystem/state files;
• adult persona/admin controls;
• exposing household/location/private telemetry beyond what the child experience genuinely needs.

Adrian/admin surface principles

The admin UI should answer, quickly:

• Is SPARK healthy?
• What is running, and is it functionally alive?
• What sensors/data are stale?
• What is SPARK currently doing and why?
• What did SPARK perceive, infer, remember, and learn?
• What provenance/evidence supports a durable claim?
• Which contextual preferences are active, with confidence, decay, contradictions, and causal record IDs?
• What actions were blocked/allowed by deterministic gates?
• Who owns GPIO right now and why?
• What privacy-sensitive data is retained and where?
• Are there pending self-evolution requests/PRs?
• What branch/commit is deployed on the Pi versus current master?
• What requires operator attention?

Candidate admin areas:

Overview

Health rollup, current activity, battery, connectivity, deployed revision, pending alerts.

Cognition / memory

Recent thoughts with provenance labels; durable memories; supersession/correction history; evidence references; retrieval/explanation tools.

Learning

Contextual preferences grouped by person/context/options, confidence trajectory, evidence and contradiction records, manual disable/correction without deleting history.

Body / authority

Motion permission, wheel-on-blocks state, current GPIO lease owner/token generation/expiry, exploration intent separately, safe stop/yield controls.

Services / diagnostics

Process state, functional heartbeat, sensor freshness, failure streaks, recent errors/log excerpts, restart controls with explicit confirmation and post-restart verification.

Privacy / data

Retention summary, data sources, disclosure surfaces, export/delete paths consistent with #173 once defined.

Configuration

Only configuration with a real operator need. Avoid turning every constant in spark_config.py into a knob. Separate safe runtime settings from code-reviewed policy.

Evolution

Pending Obi/Adrian change requests, queue/build state, PR links, budgets, review status. Preserve human merge authority.

Backup / recovery

Export state, restore with validation, and clearly distinguish append-only history from ephemeral runtime state.

Security and policy constraints

• Explicit auth/role separation; do not infer “admin” merely from being on LAN.
• Public endpoints remain intentionally minimal and privacy-filtered.
• Obi cannot obtain admin authority through prompt injection or model-generated actions.
• Dangerous admin actions require deterministic server-side authorization and explicit confirmation.
• Never expose secrets in config APIs or rendered HTML.
• Do not create browser endpoints that permit arbitrary shell/file access.
• Direct restart/reset/delete/restore actions must have post-action verification and useful failure states.
• The UI may explain deterministic policy; it must not replace it.

Relationship to existing issue #38

Audit #38 rather than implementing it literally. Its old settings-panel proposal predates current provenance, health, preference, lease, and trust-boundary architecture and contains stale timing/model assumptions. Salvage useful intent (read-only config, backup/export, carefully bounded admin settings) while replacing obsolete details.

Deliverables

1. Current-state UI/API/auth inventory.
2. Information architecture for Public vs Obi vs Admin surfaces.
3. Wireframe-level design or HTML prototype using the existing visual language where sensible.
4. Gap analysis: APIs/data needed for the new views versus APIs that should be deprecated.
5. Security/privacy review.
6. Implementation plan split into small PRs; prioritize read-only observability before mutation controls.

Acceptance

• A child-facing user cannot accidentally enter an operator/debug surface.
• An admin can understand SPARK's health, cognition, learned behavior, authority state, and deployed revision without SSH for routine inspection.
• Provenance and preference explanations are visible enough to answer “why does SPARK think/do this?”
• Health UI distinguishes process state, functional liveness, and sensor freshness.
• Exploration intent and GPIO authority are shown as separate concepts.
• Old/stale controls are explicitly removed or justified rather than automatically carried forward.
• feat(web-ui): Settings panel — view, edit, backup and export config #38 is superseded, narrowed, or decomposed based on the audit rather than blindly implemented.
• No new model permissions or direct code-merge authority are introduced.

[adrianwedd]

Grooming 2026-08-26 — unchanged and valid; #38 closed into it, and two new data sources exist

#38 is now closed as superseded by this issue, per this body's own
instruction to audit rather than implement it. The salvageable intent (read-only
config exposure, backup/export, bounded admin settings) is already enumerated
here; the obsolete specifics are recorded in #38's closing comment
(PX_MIND_BACKEND as a claude/ollama switch, PX_OLLAMA_HOST=M1.local,
spark_quiet_mode as a plain toggle, browser-writable .env, a masked
ANTHROPIC_API_KEY that does not exist on this host).

Two admin-surface questions in this body now have real answers to render,
both landed since filing:

• "What did SPARK perceive, infer, remember, and learn?" — src/pxh/people.py
  (feat(memory): person-memory writer — deterministic, evidence-minimal, firewalled #297–feat(memory): person-fact retrieval into exactly two prompts #299) is a structured person-fact store with subjects, polarity, expiry
  and provenance. The "SPARK has noticed you often choose X after school…" panel
  described under Obi-surface principles now has a backing store rather than
  needing one invented.
• "Why is SPARK quiet?" — state(quiet): make quiet mode attributable, bounded and explainable #209/Quiet mode latched again via legacy key write, bypassing the #285 canonical writer (>26h of suppressed expression) #303 replaced the naked boolean with a
  canonical quiet_state record carrying source, reason, set_at and
  expires_at. The admin UI can now literally answer the question this body
  says a bare toggle cannot.

One addition worth folding into the audit scope: deployed-revision drift is
now a live operational hazard, not a nicety. #300 is an outage caused purely by
a launcher that exists in the repo and not on the robot. "What branch/commit is
deployed on the Pi versus current master" should extend to what is installed
(/usr/local/sbin/, /etc/sudoers.d/), not just what is committed.

[adrianwedd]

Next product pass: audit the internal Web UI before adding more controls

The reliability/IO work is now deliberately entering a few-day natural observation window. This makes #188 a good candidate for the next product design pass rather than another daemon intervention.

The internal UI has grown behind the architecture. Since this issue was filed, it now has substantially better data to render: person memory (#297–#299), canonical quiet-state provenance (#303), long-term memory health (#289/#294), deployed-vs-installed drift exposed by #300, richer PSI/cgroup telemetry, GPIO lease state, and clearer resident-brain health semantics.

Recommendation when we pick this up: start with a current-state UI/API/auth audit and information architecture only. Do not implement the old dashboard incrementally or resurrect #38's stale settings model. The highest-value admin surface should answer, without SSH:

• what needs attention now;
• what is functionally alive vs merely active;
• why SPARK is quiet / unable to move / not remembering;
• what revision is committed and what privileged artifacts are actually installed;
• recent cognition, person memories and provenance;
• current GPIO/motion authority;
• sensor/perception freshness and current resource pressure.

For Obi, keep a separate companion surface centred on conversation, shared memory/projects and play — no daemon/config/tool-console leakage.

Leave #188 open; this comment is a sequencing note. Let SPARK run naturally for the next few days, then a focused UI audit/design goal is a strong candidate for the next frontier-model pass.

[adrianwedd]

One more UI-specific implication from the last deploy cycle: the current internal Web UI should not treat settings as the primary admin abstraction. The operational questions that repeatedly mattered were state explanation and deployment truth — e.g. API healthy but MOTD broken on encode, repo code merged but root launcher not installed, quiet mode true with provenance, long-term memory overdue while liveness remained green. The overhaul should therefore lead with read-only explainability/attention surfaces and only add mutation controls after those truths are visible.