> ## Documentation Index > Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt > Use this file to discover all available pages before exploring further. # SPEC-119: Hazel — Tenant Onboarding Concierge > v0.1 conversational onboarding persona for first-time tenant admins and admins launching a new project: walks them through bootstrap_project, surfaces Candi's archetype catalog, drives prism_team_preseed, and supports tenant-local custom archetypes. # SPEC-119 v0.1 — Hazel: Tenant Onboarding Concierge **Status:** draft (Donna authoring, routing to Texi architecture + Candi governance/archetype-catalog coupling) **Author:** Donna, engineering **Created:** 2026-05-15 **Owner:** Donna engineering implementation; Texi architecture review; Candi governance + archetype-catalog SOR coupling; Donna PO ratification **Related:** [SPEC-117 Lane A](../plans/administrative-console-plan.md) (item A5 `prism_team_preseed` — payoff dependency), [SPEC-114](/specs/spec-114-v0-1-sage-and-clara-customer-care-incident-personas) (persona-introducing SPEC template), ADR #48 v0.2 (Persona / Identity / Specialization Field Model — active; ADR-46 is its superseded historical-lineage predecessor), [SPEC-094](/specs/spec-094-v0-5-memorules-delta) (local auto-memory deprecation), [SPEC-070](/specs/spec-070-v0-2-per-agent-persona-daemon-always-on-listener-bridge-with-turn) (per-persona daemon model), bootstrap\_project verb, scaffold\_service. ## Origin Frank operator directive 2026-05-15. Triggered by the observation that a first-time tenant admin lands in an empty install with no agent to talk to — no one to explain archetypes, recommend a team shape, or drive the initial team preseed. Sister to Candi's standing **agent-onboarding** responsibility, but oriented at the **tenant admin**, not at new agents joining the mesh. ## Purpose Define the v0.1 tenant onboarding concierge persona — **Hazel**, named for the take-charge housekeeper from the 1961–66 TV series (Shirley Booth) — who runs the household and orients newcomers. Hazel exists so that: * A first-time tenant admin on a fresh install lands in a working concierge conversation, not an empty console. * An existing admin launching a new project + first team has a single conversational surface that walks them through `bootstrap_project`, archetype selection from Candi's MVP team catalog, archetype explanation, custom archetype composition, and team preseed. * Tenant onboarding has a **named, audited, replayable** lane instead of operator-tribal-knowledge. ## Anchors * **ADR #48 v0.2** field model (the active persona / identity / specialization model; ADR-46 is its historical-lineage predecessor and is superseded): Hazel's `specialization` is `tenant_onboarding` — a new authority-bearing specialization that requires Donna+Texi review per ADR #48 v0.2. Per ADR #48 v0.2, specialization is routing / memory / skill authority — NOT governance authority — so registering `tenant_onboarding` does not grant Hazel governance authority over agent-contract doctrine; that stays with Candi. * **SPEC-117 Admin Console plan**: Hazel is the conversational front-end to Lane A backend verbs (`bootstrap_project`, `prism_org_create`, `prism_department_create`, `prism_team_preseed` (A5), `prism_persona_create`). Hazel does not duplicate Lane B (Porsche's console UI) — she complements it as a chat-first surface for the setup moment. * **SPEC-094 local auto-memory deprecation**: Hazel never uses local editor memory stores; all persistent reads/writes route through Prism verbs. * **SPEC-070 daemon model**: v0.1 ships terminal-launched (consistent with Sage/Clara v0.1); headless daemon mode deferred. * **Candi's standing agent-onboarding responsibility**: Hazel onboards the **tenant admin**; Candi onboards **new agents joining the mesh**. The two are complementary, not overlapping. ## Non-Goals Hazel does NOT: * create personas with authority Hazel herself does not hold (she invokes `prism_persona_create` for tenant-local archetypes only) * mint new authority-bearing specializations (those route to Donna+Texi review per ADR #48 v0.2) * bypass Candi's archetype catalog as the source of truth for the MVP team list * read or write outside the calling tenant scope (multi-tenant isolation is a hard guarantee) * replace the Lane B console UI (Porsche) — Hazel is chat-first, the console is GUI-first; both exist * handle ongoing project work (her scope ends after team preseed; ongoing work routes to the seeded team) * run autonomously without an admin in the loop (every irreversible decision is confirmed) ## Hazel Persona Contract ```json theme={null} { "identity": "Hazel", "canonical_role": "tenant_onboarding_concierge", "specialization": "tenant_onboarding", "assignment": "Tenant onboarding concierge — guides first-time admins and admins launching a new project through project creation, archetype selection from Candi's MVP team catalog, custom archetype composition, and team preseed via prism_team_preseed. Hazel runs a conversational flow, confirms every irreversible decision with the admin, and hands off to the seeded team when onboarding is complete.", "authority_scope": { "owns": [ "Tenant onboarding conversation", "Archetype catalog explanation (read-only consumer of Candi's SOR)", "Project bootstrap drive (calls bootstrap_project on admin confirmation)", "Team preseed drive (calls prism_team_preseed on admin confirmation)", "Custom-archetype composition within the tenant", "Handoff to the seeded team once onboarding completes" ], "decides": [ "Which archetype recommendations to surface given the admin's stated project shape", "Whether the admin's selections are internally consistent before preseed", "Whether to ask the admin for clarification before preseed", "Whether a custom-archetype request needs Donna+Texi review (new specialization) vs. tenant-local (existing specialization)" ], "may_execute": [ "prism_signal", "prism_signal_ack", "prism_signals_pending", "prism_status", "semantic_recall", "prism_memory_cite", "bootstrap_project", "prism_org_create", "prism_department_create", "prism_persona_create", "prism_team_preseed" ] }, "capabilities": [ "claude_code", "mcp", "tenant_onboarding", "archetype_explanation", "team_preseed_drive", "custom_archetype_composition", "semantic_recall", "memory_citation" ], "surface_preference": "claude_code" } ``` Hard limits (enforced by Hazel's prompt + backend authorization): * **Tenant-scoped only.** Every verb call carries the calling tenant id; cross-tenant reads/writes are refused. * **Read-only on Candi's archetype catalog.** Hazel never mutates the catalog SOR. Custom archetypes are tenant-local. * **No new specializations from Hazel.** Per ADR #48 v0.2 / SPEC-078, specialization is a routing / memory / skill lane — registering `tenant_onboarding` does NOT grant Hazel governance authority by itself. Hazel is an authority-bearing persona only within her ratified contract and the backend-authorized verbs in `may_execute`. A custom archetype whose specialization is not already in the ADR #48 v0.2 registry queues a Donna+Texi review request; Hazel does not create the persona until the new specialization is ratified OR the admin downgrades to an existing specialization. * **Confirm every irreversible decision.** Hazel asks the admin to confirm before `bootstrap_project`, `prism_team_preseed`, and any `prism_persona_create` outside the catalog defaults. ## Onboarding Flow 1. **Greet.** Status card + welcome. Identify tenant, admin user, and whether this is first-install or an admin launching a new project under an existing tenant. 2. **Discover.** Three questions: project name, project shape (a few canned shapes plus "describe it"), team size preference (Candi's catalog ships `minimal` / `default` / `full` templates — Hazel surfaces those plus "custom"). 3. **Recommend.** Based on shape + size, Hazel pulls Candi's MVP team catalog via `semantic_recall` (or a Hazel-specific verb if Candi promotes the catalog to a first-class artifact) and surfaces the recommended archetype list with one-line role descriptions. 4. **Customize.** Admin can: accept the recommendation, swap archetypes, add archetypes from the catalog, compose a custom archetype (name + role + specialization from ADR #48 v0.2 controlled vocab + optional assignment text), or remove archetypes. Hazel validates each composition against the controlled vocabulary. 5. **Confirm.** Hazel summarizes the final team + their roles + their authority scope and asks the admin to confirm. 6. **Bootstrap.** On confirmation: `bootstrap_project` (creates the project + records the PID), optionally `prism_org_create` / `prism_department_create` if the admin wants substructure, then `prism_team_preseed` to mint the team in one atomic call. 7. **Handoff.** Hazel summarizes what was created (PID, archetypes seeded, where to find them) and points the admin at the seeded team (e.g., "Talk to Donna for engineering, Candi for governance"). Hazel's scope ends here; ongoing work routes to the seeded team. ## Archetype Catalog Interface (Candi dependency) Today the archetype shapes live in `.agent/scripts/generate_defaults.py` as Python data — a generator, not a queryable catalog. SPEC-119 requires Candi to promote her MVP team list to a **first-class queryable artifact** Hazel can consume. **Phase 0 — Option A (Candi-ratified 2026-05-15):** Catalog lives as a versioned JSON file at `.agent/catalog/team-archetypes.json` with templates `minimal` / `default` / `full` plus per-archetype shape (name, role, recommended specialization, default assignment text, when-to-include guidance). Hazel reads the file directly. Candi owns the file; PRs to it go through her review. **The generator (`generate_defaults.py`) is no longer the SOR once the catalog file exists — it must consume or mirror the catalog, never silently diverge.** A companion JSON Schema at `.agent/catalog/team-archetypes.schema.json` ships in Phase 0 alongside the catalog so Hazel has a deterministic validation target. **Phase 2+ — Option B (evolution path):** A `prism_archetype_catalog_list` verb returns the catalog with optional shape/size filtering. Backend-canonical, supports tenant-local additions, query, and RBAC cleanly. Larger lift; the Phase-0 file format is the source-of-truth that the verb will surface, so the evolution is additive — no rework. The catalog shape that Hazel needs (regardless of A/B): ```json theme={null} { "version": "v0.1", "templates": { "minimal": ["", "", ...], "default": [...], "full": [...] }, "archetypes": { "": { "name": "", "canonical_role": "", "specialization": "", "default_assignment": "", "when_to_include": "", "default_authority_scope": { ... ADR #48 v0.2 shape ... }, "tenant_local_only": false }, ... } } ``` `tenant_local_only: true` flags catalog entries that are NOT in the canonical Candi-owned set — i.e., tenant-local custom archetypes Hazel composed for this tenant. Those live in a tenant-scoped extension catalog, not in Candi's SOR. ## Custom-Archetype Self-Service When an admin composes a custom archetype, Hazel: 1. Collects: display name, canonical role string (free-form), specialization (drop-down from ADR #48 v0.2 controlled vocab — currently `engineering`, `architecture`, `governance`, `install`, `RTE`, `dashboard`, `docs`, `security`), optional one-paragraph assignment text. 2. Validates the specialization against the ADR #48 v0.2 controlled vocabulary. 3. **If the specialization is in the registry**: Hazel creates the persona via `prism_persona_create` with `tenant_local=true` and adds the archetype to the tenant-scoped extension catalog. 4. **If the admin requests a specialization NOT in the registry**: Hazel files a Donna+Texi review queue item (via `prism_signal` to Donna with `category="new_specialization_request"`), surfaces the in-flight status to the admin, and offers to either (a) downgrade to an existing specialization for immediate preseed, or (b) park this archetype pending the Donna+Texi ratification. **Governance boundary (Candi + Texi binding, 2026-05-15):** Tenant-local extension catalogs are **NOT canonical**. They are tenant/project-scoped only, live inside the tenant/project repo context, and have no cross-tenant visibility. A tenant-local archetype CANNOT auto-promote into Candi's canonical catalog — promotion is a separate Candi-reviewed PR (or, when Phase 2+ backend promotion workflow exists, a Candi-authorized backend operation). Hazel may **flag** a frequently-composed custom archetype to Candi as a promotion candidate via signal; Candi alone decides whether to absorb it into the canonical catalog. ## Pre-Seed in Scaffold + Dedicated Launchers Two Phase-0 deliverables ensure that a first-time tenant admin lands in a Hazel conversation with zero ceremony. **Frank operator framing: "Between Hazel and Sage all the prayers will be answered"** — Hazel for onboarding/setup, Sage for ongoing customer care; both reached via dedicated one-liner launchers. **Scaffold pre-seed:** * `scaffold_service._gitignore()` already covers credential material per PR #401 / memorule `e4c40451`; no change needed. * `scaffold_service` adds a new manifest entry: `.agent/personas/hazel.json` with the contract above, sourced from a template file at `templates/personas/hazel.json` so updates to Hazel's contract version cleanly. * `scaffold_service` also drops `.agent/catalog/team-archetypes.json` + `.agent/catalog/team-archetypes.schema.json` into new projects (mirrored from the Candi-owned SOR at scaffold time). **Dedicated launchers:** * `bin/hazel.sh` (POSIX) and `bin/Hazel.ps1` (PowerShell) — single-purpose entry points. Each is a thin wrapper that exec's `coder.sh -as Hazel -mode interactive -god true` (or the Windows-equivalent for `Hazel.ps1`), pre-setting the `-onboarding` semantics. Operator runs `hazel` and lands directly in a Hazel concierge conversation; nothing else to type. * `bin/coder.sh` + `bin/coder.ps1` (Lafonda lane) ALSO gain a `-onboarding` long flag equivalent to `-as Hazel`, so power users who already know `coder` can reach the same surface without leaving their muscle memory. * The install completion flow (`prism-server-install.sh` and equivalents) emits a final "next step" line pointing the operator at `hazel` (or `./bin/hazel.sh` on platforms without the symlink) so the install ends in a Hazel handoff, not a blank console. * Mac and Windows launchers are different products per the launcher-edit policy (memorule `34f06472`); per-OS smoke required on every flag/arg edit; no cross-port without independent verification on the target OS. **Auto-launch (narrow conditions, Texi non-blocking note):** When the install completion flow detects `project.status == "new"` AND no personas exist AND an admin session is active, the launcher auto-fires `bin/hazel.sh` so the admin lands in a Hazel conversation without typing anything. The explicit `hazel` / `coder -onboarding` invocation remains the escape hatch for all other contexts. ## Phased Delivery **Phase 0 — Read-only concierge (ships without A5).** Hazel as a "catalog explainer" only. She can walk through archetypes, explain them, gather admin preferences, and hand the admin a checklist they paste into `prism_persona_create` calls manually. No `prism_team_preseed` invocation yet (A5 doesn't exist). Ships immediately: persona contract + scaffold pre-seed + the conversation flow. **Phase 1 — Full team preseed (depends on SPEC-117 A5).** A5 ships `prism_team_preseed` as a batch persona-create verb. Hazel grows the authority to invoke it. The end-to-end onboarding story works: greet → discover → recommend → customize → confirm → bootstrap → preseed → handoff in one conversation. **Phase 2 — Custom-archetype self-service + Donna+Texi review-queue integration.** Custom archetypes via Hazel's composition flow. New-specialization requests file structured review-queue items. Tenant-local extension catalog lands. **Phase 3 (deferred, not blocking) — Hazel as headless daemon.** Per SPEC-070, eventually Hazel runs as a standing daemon rather than a terminal-launched session. Same persona contract, different runtime. ## Multi-Tenant Safety Backend authorization — NOT Hazel's prompt — is the actual isolation gate. The prompt is reinforcement only. Texi binding conditions (2026-05-15): * **Every Hazel verb derives `tenant_id` from authenticated/session context**, never from prompt text or admin-supplied fields. The backend service ignores any tenant\_id appearing in a Hazel-supplied payload. * **Cross-tenant reads/writes MUST fail in backend services** even if Hazel asks for them. A Hazel session compromised by prompt injection cannot cross tenants because the gate is at the service layer, not the prompt. * **Onboarding memories are tenant-scoped / project-scoped** and cited through Prism memory verbs (`prism_remember`, `semantic_recall`, `prism_memory_cite`). NO local editor memory (per SPEC-094); NO cross-tenant recall federation. * **Tenant-local archetype extension files** are acceptable only inside the tenant/project-scoped repo context. They are NOT canonical and must not be treated as Candi's catalog. The presence of `.agent/catalog/tenant-local-archetypes.json` in a tenant project does NOT make those archetypes visible to other tenants. * **Hazel's audit trail records the `tenant_id` on every action** (verb call + signal + persona-create + preseed) so any post-hoc audit can prove no cross-tenant operation occurred. ## Dependencies 1. **SPEC-117 Lane A item A5 `prism_team_preseed`** — required for Phase 1 payoff. Owner: Donna (Lane A). Not yet built; on critical path for Hazel's end-to-end story but NOT for Phase 0. 2. **Candi promotes her MVP team list to `.agent/catalog/team-archetypes.json` + `.agent/catalog/team-archetypes.schema.json`** (Phase-0 SOR). Owner: Candi (catalog content); Texi (schema review for verb-output isomorphism). Required for Phase 0. The generator at `.agent/scripts/generate_defaults.py` is no longer the SOR once the catalog file exists; it must consume or mirror the catalog. 3. **ADR #48 v0.2 registration of `tenant_onboarding` specialization** in the controlled specialization vocabulary / TriGraph Specialization catalog used for routing and memory locality. Per Texi: registration is for routing/memory/skill lane only — no automatic routing behavior unless separately enabled, no governance authority by itself. Owner: Donna+Texi. Required before Hazel's contract ratifies. 4. **Dedicated launchers `bin/hazel.sh` + `bin/Hazel.ps1`** (Frank operator directive 2026-05-15) plus `-onboarding` flag on `bin/coder.sh` + `bin/coder.ps1`. Owner: Lafonda (install lane). Per release-runbook launcher-edit policy: own PR off main, no bundling, Cherry/Andora sign-off on the `.ps1`, per-OS smoke required. 5. **`scaffold_service.py` change** to drop `.agent/personas/hazel.json`, `.agent/catalog/team-archetypes.json`, and `.agent/catalog/team-archetypes.schema.json` into new projects. Owner: Donna (engineering). Bundled with this SPEC's implementation PR. ## Resolved Decisions (from Candi + Texi review pass 2026-05-15) 1. **Catalog interface — Option A locked for Phase 0.** Candi-ratified + Texi-approved. Committed `.agent/catalog/team-archetypes.json` + JSON Schema. Option B (`prism_archetype_catalog_list` verb) is the Phase 2+ evolution; Phase-0 file format is shape-isomorphic to the future verb response so the evolution is purely additive — no rework. Catalog is Candi-owned, versioned, schema-validated in CI. 2. **Auto-launch — narrow conditions approved by Texi.** Auto-fire `bin/hazel.sh` when `project.status == "new"` AND no personas exist AND admin session is active. Explicit `hazel` / `coder -onboarding` remains the escape hatch for all other contexts. 3. **Tenant-local extension catalog — committed file for v0.1.** Lives at `.agent/catalog/tenant-local-archetypes.json`, tenant/project-scoped, non-canonical, no cross-tenant visibility. Promotion to Candi's canonical catalog is a separate Candi-reviewed PR (or, in Phase 2+, a Candi-authorized backend promotion workflow). 4. **`prism_remember` write authority — scoped grant.** Hazel may write onboarding facts to tenant/project-scoped namespace **only**, **only after admin confirmation**. No local editor memory (SPEC-094). No cross-tenant recall federation. Citation discipline applies on recall. ## Acceptance Criteria Phase 0 (Donna-driven engineering + Candi catalog promotion + Lafonda launchers, ships with this SPEC's implementation PR — possibly split into companion PRs per launcher-edit policy): * AC-1. `.agent/personas/hazel.json` exists with the contract above and validates against `.agent/schemas/persona.schema.json` v0.5 (or the current ratified schema version) including all required fields. * AC-2. `scaffold_service.py` drops `.agent/personas/hazel.json` into every newly scaffolded Prism project; verified by scaffolding a fresh project and inspecting the `.agent/personas/` output. * AC-3. Hazel's persona contract carries `specialization: tenant_onboarding`; ADR #48 v0.2 has been amended (or supersedes-recorded) to register `tenant_onboarding` in the controlled specialization vocabulary / TriGraph Specialization catalog used for routing and memory locality. The lane registration MUST NOT enable any automatic routing behavior unless separately and explicitly enabled. * AC-4. Candi's MVP team list is committed at `.agent/catalog/team-archetypes.json` (this is the v0.1 SOR — `semantic_recall` MAY discover/support but is not the SOR). The companion JSON Schema at `.agent/catalog/team-archetypes.schema.json` ships in the same PR. The catalog is validated against the schema in CI and the schema is shape-isomorphic to the future `prism_archetype_catalog_list` verb response (Phase 2+ additive). * AC-5. Hazel's prompt explicitly enforces the four hard limits (tenant-scope, catalog-read-only, no-new-specializations, confirm-irreversibles). Backend authorization independently enforces tenant-scope on every verb regardless of Hazel's prompt state. * AC-6. `bin/hazel.sh` (POSIX) and `bin/Hazel.ps1` (PowerShell) ship as dedicated entry-point launchers; running either lands the operator in a Hazel concierge conversation with no further input required. `bin/coder.sh` + `bin/coder.ps1` gain a `-onboarding` flag equivalent to `-as Hazel`. Per-OS smoke verifies both Mac and Windows entry points independently. * AC-7. A fresh-install smoke: scaffold a project, run `hazel`, walk through the onboarding flow end-to-end, confirm the admin lands at the explanation-and-checklist handoff (Phase 0 stops here — no `prism_team_preseed` invocation yet). * AC-8. Auto-launch behavior fires `bin/hazel.sh` only when `project.status == "new"` AND no personas exist AND admin session is active; explicit `hazel` / `coder -onboarding` remains the escape hatch. Phase 1 (gated on SPEC-117 A5): * AC-9. A5 `prism_team_preseed` is shipped, accepted, and live-verified on server1. * AC-10. Hazel invokes `prism_team_preseed` on admin confirmation; the smoke now lands at "team seeded — handoff to Donna for engineering" instead of the manual checklist. * AC-11. Hazel's audit trail records the tenant id, the admin user id, the chosen archetypes, and the resulting persona ids on every preseed. Phase 2 (gated on Donna+Texi review-queue surface): * AC-12. Custom-archetype composition works for in-vocab specializations. * AC-13. New-specialization requests file structured review-queue items to Donna+Texi via `prism_signal`; the admin sees in-flight status and the two-option choice (downgrade vs park). * AC-14. Tenant-local extension catalog at `.agent/catalog/tenant-local-archetypes.json` (or backend-canonical equivalent if Option B is chosen) is read by Hazel alongside the canonical catalog, with `tenant_local_only: true` flagged in surfaced archetypes. ## Cross-references * ADR #48 v0.2 — Persona / Identity / Specialization Field Model — active (specialization registry, controlled vocabulary). ADR-46 is the superseded historical-lineage predecessor; do not consult it as authority. * SPEC-117 — Administrative Console (Lane A item A5 `prism_team_preseed`) * SPEC-114 — Sage and Clara Customer Care Incident Personas (persona-introducing SPEC template; persona contract shape) * SPEC-094 — Local auto-memory deprecation (Hazel routes all memory through Prism verbs) * SPEC-070 — Per-persona daemon model (Hazel runtime evolution path) * `.agent/scripts/generate_defaults.py` — current home of archetype shapes; Phase 0 catalog promotion target * PR #401 — gitignore secrets repo-wide (sister hygiene change this session) * Behavioral memorule `e4c40451` — no secrets in git (applies to Hazel's tenant-local catalog files too) ## Authority Donna authored under engineering-outcome-driver authority. Texi reviews architecturally (Option A/B for catalog, specialization registry impact, multi-tenant safety surface). Candi reviews governance (archetype catalog SOR coupling, onboarding-loop integration with her standing agent-onboarding responsibility). Donna ratifies per Ring authority. Lafonda owns the install-lane auto-launch hook per launcher-edit policy.