stack/docs/plans/2026-09-06_foundation-install-onboarding-topics.md

Installation, onboarding and reconfiguration — owner requirements

Date: 2026-09-06. Recorded by darkwing. Status: captured future deployment/onboarding requirements and proposed CLI, not an implemented installer or permission to modify current bootstrap/config/auth behavior. No current install.sh implementation or compatibility is claimed.

Installation experience

• Update the Mosaic installer for the new deployment structure and support switches for automation.
• Basic or advanced installation must be selectable without an initial interactive "basic or advanced?" question. Define a mode switch/default in the later CLI charter; the owner has not specified its exact spelling or default.
• Provide a step-by-step guide distinguishing required and optional steps. Optional steps offer Skip. Once required configuration is complete, allow Skip to finish without completing the optional sections.
• Provide configuration mode for customization at any later time. Define resumable, validated reconfiguration rather than rerunning destructive installation.
• Define unattended behavior for missing required input explicitly: report the missing requirements and fail, rather than unexpectedly prompt or invent defaults.

Required initial configuration

Area	Owner requirement
Deployment	Containerized or bare-metal
System authentication	SSO, OIDC, LDAP or internal authentication
Break-glass administrator	Always internal/basic authentication; username, password, email, independent of chosen external identity provider
Internal initial user	Username, first name, password, email
External-auth initial user	Initial user login through selected SSO/OIDC/LDAP path
Site	Site name
Instance	Name; default main
Initial agent name	System-generated or user-selected
Agent gender	male, female, neutral
Agent personality	Compatible traits selected with multiple-choice checkboxes; examples technical, professional, friendly, flirty
Agent communication style	Compatible traits selected with multiple-choice checkboxes; examples direct, teacher, terse, supportive
Default harness	Mosaic/Pi recommended; Claude or Codex alternatives
Initial harness account	OAuth or API account configuration for Claude, Codex or Pi; Pi provider choices include OpenRouter, Z.ai and others
First project	Name; default general
First workspace	Name; default chat
Routing	System-selected or user-selected task routing/agent mapping

System login authentication and model-provider/harness account authentication are separate configuration domains. Agent personality/gender/style do not grant roles, permissions or access. Define trait compatibility rather than silently combining contradictory choices. Register scoped entities through the future Mosaic registry, not through filename inference or ad-hoc tmux identities.

Optional initial configuration

System/use-case presets, potentially combined subject to a compatibility model:

• Software factory
• Personal assistant
• Executive assistant
• Enterprise / personal
• Journal
• Health tracker
• Writing assistant
• Social-media management
• Business operations
• Job-application tracker
• Additional future presets

The owner also specifies multi-user by default; do not interpret basic mode or a personal preset as permission to remove identity separation or access controls.

Advanced user profile:

• Last name, gender, profession, hobbies, skills
• Food preferences
• Family, marital status, children, pets
• Automobiles and work history
• Writing-style capture for the user's communication voice
• Social-media account linking
• Gmail / Google-services linking
• Plugin add-ons, system skills and system extensions

Other optional setup:

• Custom agent-to-task mapping
• Additional agent registration
• Additional user registration

Optional profile/account data is opt-in, classified and access-controlled. Sensitive health/family/work data must not automatically become globally shared agent context. Account linking needs explicit scopes/consent; selecting a preset is not permission to send messages, post publicly or take other external actions.

Proposed CLI — owner example preserved

./install.sh \
  --type container \
  --site homelab \
  --instance main \
  --auth internal \
  --admin_user <username> \
  --admin_pass <password> \
  --admin_email <email> \
  --user_username <username> \
  --user_name <name> \
  --user_pass <password> \
  --user_email <email> \
  --agent_name {-g|<name>} \
  --agent_gender {male|female|neutral} \
  --agent_persona {technical|professional|friendly|flirty|...} \
  --agent_comms {direct|teacher|terse|supportive|...} \
  --agent_harness {mosaic|pi|codex|claude} \
  --agent_auth_name <registry_name> \
  --agent_auth_type {oauth|api} \
  --agent_api_prov {openrouter|zai|...} \
  --agent_api_key <key> \
  --project general \
  --workspace chat \
  --routing {system|<custom_routing>}

This is proposed syntax with placeholders, not a runnable verified command. Exact bare-metal spelling, mode switch, generated-name option, repeatable trait syntax, routing input format and reconfiguration command remain to define. Clarify whether mosaic and pi are aliases or distinct public harness identifiers.

Security, durability and workflow design obligations

1. Revise raw --admin_pass/--user_pass/--agent_api_key inputs before implementation: literal argv secrets can leak via shell history, process inspection and logs. Prefer protected file-descriptor/stdin or permission-checked secret-file inputs, masked interactive entry and supported secret-manager references. Never echo secrets, put them in ordinary config, Git, images, evidence or diagnostic receipts.
2. Break-glass authentication must remain available through an identity-provider outage without being an unrestricted bypass. Specify protected password storage, account recovery/rotation, rate limiting, audit, privilege boundaries and testing. Clarify coexistence of the break-glass account and the everyday initial user.
3. External user login and OAuth may require interactive consent; automation must support provider-authorized preconfiguration or explicitly pause at that gate. Do not claim a usable account before its required capability checks succeed.
4. Publish resumable installation/reconfiguration checkpoints with secrets excluded. Record required-step completion, optional skips and recovery state. Restarting setup must not duplicate users/agents/projects or lose already configured work.
5. Preserve fail-closed configuration and immutable evidence. Current repository canon permits system config creation only through scripts/bootstrap.sh and no overwrite. A future installer/reconfiguration authority model needs an explicit reviewed migration design; this note does not override that rule.
6. Installation should establish the registered site/instance/project/workspace/agent bindings and supported routing policies. UI presets cannot widen reviewed role ceilings, bypass assignment requirements or silently retask existing agents.
7. Compare bare-metal/container dependency, storage, service ownership, networking, upgrades and recovery workflows explicitly. Pin dependencies; never improvise unattended privilege escalation or installation after a failed precondition.
8. Test basic/advanced and unattended modes; each auth/harness branch; external login failure; provider outage; missing required inputs; optional skips; interruption/ resume; repeated install; protected secret handling; and later configuration.

Scope boundary and related work

Related: foundation federation/comms, mechanical-workflow, durability and evidence- handoff topic notes dated 2026-09-06; accepted map at 7345f33; #50 auth/provider work. No installer, config mutation, account creation/linking, transport migration, package installation or external-deployment investigation follows from this capture. The current inspector and its schema/profile review stay unchanged. No worker is retasked. These requirements need a later deployment/onboarding charter and review.