jason.woltje
193479b52d
Mosaic concepts pages now own the adapted content; source/license metadata under docs/reference/concepts. Adds ACT-1 agent-context planning capture, pinned concept test package + preparation utility, foundation observation notes (durability, evidence, federation, onboarding, workflow), and the #1495 consolidation assessment. TOOLS.md updated for the host-dev launcher.
161 lines
8.0 KiB
Markdown
161 lines
8.0 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
./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.
|