feat(fleet): system-type profiles (H2) (#660)

packages/mosaic/framework/fleet/profiles/business.yaml

@@ -0,0 +1,30 @@
+id: business
+title: Business (Company-in-a-Box)
+description: >-
+  A full company org: the CEO sets direction, the COO and CFO run execution and
+  finance, and the functional leads (product, marketing, sales, operations,
+  customer success) plus a small engineering slice deliver the work. reports_to
+  encodes the org chart.
+lead: ceo
+floor:
+  - ceo
+roster:
+  - class: ceo
+  - class: coo
+    reports_to: ceo
+  - class: cfo
+    reports_to: ceo
+  - class: product-manager
+    reports_to: coo
+  - class: marketing-lead
+    reports_to: coo
+  - class: sales-lead
+    reports_to: coo
+  - class: operations-manager
+    reports_to: coo
+  - class: customer-success-manager
+    reports_to: coo
+  - class: code
+    reports_to: product-manager
+  - class: review
+    reports_to: product-manager

packages/mosaic/framework/fleet/profiles/marketing.yaml

@@ -0,0 +1,25 @@
+id: marketing
+title: Marketing
+description: >-
+  A marketing org that owns strategy, content, channels, and growth. The
+  marketing-lead sets strategy and budget and runs a roster of content, copy,
+  SEO, social, brand, growth, and UX specialists.
+lead: marketing-lead
+floor:
+  - marketing-lead
+roster:
+  - class: marketing-lead
+  - class: content-strategist
+    reports_to: marketing-lead
+  - class: copywriter
+    reports_to: content-strategist
+  - class: seo-specialist
+    reports_to: marketing-lead
+  - class: social-media-manager
+    reports_to: content-strategist
+  - class: brand-strategist
+    reports_to: marketing-lead
+  - class: growth-marketer
+    reports_to: marketing-lead
+  - class: ux-designer
+    reports_to: marketing-lead

packages/mosaic/framework/fleet/profiles/personal-assistant.yaml

@@ -0,0 +1,19 @@
+id: personal-assistant
+title: Personal Assistant
+description: >-
+  A personal-logistics fleet for one principal: handles errands, reminders,
+  calendar, inbox triage, and ad-hoc lookups. The personal-assistant leads and
+  delegates scheduling, inbox triage, and research to specialist seats.
+lead: personal-assistant
+floor:
+  - personal-assistant
+roster:
+  - class: personal-assistant
+  - class: executive-assistant
+    reports_to: personal-assistant
+  - class: scheduler
+    reports_to: executive-assistant
+  - class: inbox-manager
+    reports_to: personal-assistant
+  - class: researcher
+    reports_to: personal-assistant

packages/mosaic/framework/fleet/profiles/research.yaml

@@ -0,0 +1,24 @@
+id: research
+title: Research
+description: >-
+  A research fleet that decomposes a question, gathers and analyzes evidence, and
+  synthesizes cited findings. The lead-researcher owns the agenda and assigns
+  individual questions to researchers and the analytics seats.
+lead: lead-researcher
+floor:
+  - lead-researcher
+roster:
+  - class: lead-researcher
+  - class: researcher
+    reports_to: lead-researcher
+    multiplicity: 2
+  - class: data-analyst
+    reports_to: lead-researcher
+  - class: data-scientist
+    reports_to: lead-researcher
+  - class: market-analyst
+    reports_to: lead-researcher
+  - class: documentation
+    reports_to: lead-researcher
+  - class: review
+    reports_to: lead-researcher

packages/mosaic/framework/fleet/profiles/software-delivery.yaml

@@ -0,0 +1,71 @@
+# Mosaic system-type profile — SCHEMA REFERENCE
+# ---------------------------------------------------------------------------
+# A profile is a DECLARATIVE mapping from a "system type" to a persona roster
+# plus its org topology. Profiles are DATA: drop a new <id>.yaml here and the
+# loader/CLI pick it up with no code change (North Star NS-9 / AC-NS-6).
+#
+# Every persona referenced below (lead, floor[], roster[].class, roster[].reports_to)
+# MUST resolve to a real persona in the library. The loader validates this against
+# the role contracts in ../roles/*.md (see LIBRARY.md for the grouped index).
+#
+# Schema (this file documents every key; other profiles omit the comments):
+#
+#   id:           kebab-case system-type id — MUST equal the filename stem.
+#   title:        human-readable name.
+#   description:  one paragraph — what this system does.
+#   lead:         persona class that coordinates the roster (the orchestrating seat).
+#   floor:        persistent minimum roster that must stay staffed (list of classes).
+#   roster:       the full default roster. Each entry:
+#                   - class:        persona class (MUST resolve to a role file).
+#                     reports_to:   optional — the class this seat reports to
+#                                   (encodes org topology). Omit for the lead.
+#                                   MUST resolve to a class present in this roster.
+#                     multiplicity: optional int (default 1) — e.g. 2 coders.
+#   notes:        optional free text.
+# ---------------------------------------------------------------------------
+id: software-delivery
+title: Software Delivery
+description: >-
+  The engineering fleet that turns ratified objectives into shipped, reviewed,
+  merged code. The lead (planner — the orchestrator seat) plans phased FRs into a
+  depends_on DAG, decomposition splits them into one-PR-each cards, coders execute
+  to green CI, and review / security-review / site-tester / merge-gate guard the
+  merge. This mirrors today's coding fleet.
+# NOTE: the canonical lead seat is the "orchestrator". In the persona library the
+# orchestrator IS the `planner` class (see roles/planner.md: "the planner role IS
+# the existing orchestrator class") — so the lead/floor reference `planner`, the
+# only class that actually resolves to a role contract.
+lead: planner
+floor:
+  - planner
+  - enhancer
+roster:
+  - class: board
+    reports_to: planner
+  - class: planner
+  - class: decomposition
+    reports_to: planner
+  - class: code
+    reports_to: decomposition
+    multiplicity: 2
+  - class: review
+    reports_to: planner
+  - class: security-review
+    reports_to: review
+  - class: site-tester
+    reports_to: review
+  - class: documentation
+    reports_to: planner
+  - class: merge-gate
+    reports_to: planner
+  - class: rebase
+    reports_to: merge-gate
+  - class: operator
+    reports_to: planner
+  - class: session-review
+    reports_to: planner
+  - class: enhancer
+    reports_to: planner
+notes: >-
+  Two-agent floor (orchestrator/planner + enhancer) is always staffed; every other
+  seat is added on demand.

packages/mosaic/framework/install.sh

@@ -24,9 +24,11 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # reconcile_framework_files (overwrite + backup-once); the rest stay user-owned.
 # User-created content in these paths survives rsync --delete.
 #
-# fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
+# fleet/* — the framework SEEDS fleet/examples, fleet/roles, fleet/profiles, and
 # fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
-# lands automatically via this sync, so no per-file entry is needed). The user's
+# and fleet/profiles/*.yaml system-type profile lands automatically via this sync,
+# so no per-file entry is needed; the preserved "fleet/*.yaml" glob is anchored to
+# the top level only and does NOT shadow fleet/profiles/*.yaml). The user's
 # own fleet files MUST
 # survive `mosaic update` (which runs this sync automatically): the active
 # roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env

packages/mosaic/src/commands/fleet-profiles.spec.ts

@@ -0,0 +1,218 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  listPersonaClasses,
+  loadProfile,
+  loadProfiles,
+  parseProfile,
+  validateProfile,
+  type FleetProfile,
+} from './fleet-profiles.js';
+
+// The real, committed library: packages/mosaic/src/commands -> framework/fleet.
+const frameworkFleet = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'framework',
+  'fleet',
+);
+const rolesDir = join(frameworkFleet, 'roles');
+const profilesDir = join(frameworkFleet, 'profiles');
+
+const realLib = { rolesDir, profilesDir };
+
+const EXPECTED_IDS = [
+  'business',
+  'marketing',
+  'personal-assistant',
+  'research',
+  'software-delivery',
+];
+
+describe('listPersonaClasses (real role library)', () => {
+  it('extracts inline `class:` markers from the role contracts', async () => {
+    const classes = await listPersonaClasses(rolesDir);
+    // Personas that carry an inline `class: X` marker.
+    expect(classes.has('code')).toBe(true);
+    expect(classes.has('marketing-lead')).toBe(true);
+    expect(classes.has('ceo')).toBe(true);
+    // support-agent's marker wraps across a newline — must still resolve.
+    expect(classes.has('support-agent')).toBe(true);
+  });
+
+  it('covers marker-less engineering personas via filename + LIBRARY index', async () => {
+    const classes = await listPersonaClasses(rolesDir);
+    // planner/decomposition have a role file but no inline marker (planner aliases
+    // the orchestrator class) — they resolve from the filename + LIBRARY.md row.
+    expect(classes.has('planner')).toBe(true);
+    expect(classes.has('decomposition')).toBe(true);
+  });
+
+  it('returns an empty set for a missing roles dir (graceful)', async () => {
+    const classes = await listPersonaClasses(join(tmpdir(), 'definitely-missing-roles-xyz'));
+    expect(classes.size).toBe(0);
+  });
+});
+
+describe('baseline profiles (real library)', () => {
+  it('loads exactly the five baseline profiles, sorted by id', async () => {
+    const profiles = await loadProfiles(realLib);
+    expect(profiles.map((p) => p.id)).toEqual(EXPECTED_IDS);
+  });
+
+  it('every referenced class resolves against the real role library (drift guard)', async () => {
+    // This is the key test: it fails if a profile drifts from the persona library.
+    const profiles = await loadProfiles(realLib);
+    const validClasses = await listPersonaClasses(rolesDir);
+    for (const profile of profiles) {
+      expect(validateProfile(profile, validClasses)).toEqual([]);
+    }
+  });
+
+  it('software-delivery has the expected lead, floor, and roster shape', async () => {
+    const profile = await loadProfile('software-delivery', realLib);
+    expect(profile.lead).toBe('planner');
+    expect(profile.floor).toEqual(['planner', 'enhancer']);
+    const code = profile.roster.find((r) => r.class === 'code');
+    expect(code?.multiplicity).toBe(2);
+    expect(code?.reportsTo).toBe('decomposition');
+  });
+
+  it('loadProfile throws on an unknown id', async () => {
+    await expect(loadProfile('does-not-exist', realLib)).rejects.toThrow(/Unknown profile/);
+  });
+});
+
+describe('parseProfile', () => {
+  it('defaults multiplicity to 1 and omits reports_to for the lead', () => {
+    const yaml = [
+      'id: x',
+      'title: X',
+      'description: a system',
+      'lead: ceo',
+      'floor: [ceo]',
+      'roster:',
+      '  - class: ceo',
+      '  - class: code',
+      '    reports_to: ceo',
+      '    multiplicity: 3',
+      '',
+    ].join('\n');
+    const profile = parseProfile(yaml);
+    expect(profile.roster[0]).toEqual({ class: 'ceo', multiplicity: 1 });
+    expect(profile.roster[1]).toEqual({ class: 'code', reportsTo: 'ceo', multiplicity: 3 });
+  });
+
+  it('rejects a profile whose id mismatches its filename', () => {
+    expect(() =>
+      parseProfile(
+        'id: other\ntitle: T\ndescription: d\nlead: ceo\nroster: [{class: ceo}]\n',
+        'expected',
+      ),
+    ).toThrow(/does not match its filename/);
+  });
+
+  it('rejects a non-integer multiplicity', () => {
+    const yaml =
+      'id: x\ntitle: T\ndescription: d\nlead: ceo\nroster:\n  - class: ceo\n    multiplicity: 1.5\n';
+    expect(() => parseProfile(yaml)).toThrow(/multiplicity/);
+  });
+});
+
+describe('validateProfile', () => {
+  const valid = new Set(['ceo', 'coo', 'code']);
+
+  it('passes a well-formed profile', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: ['ceo'],
+      roster: [
+        { class: 'ceo', multiplicity: 1 },
+        { class: 'coo', reportsTo: 'ceo', multiplicity: 1 },
+      ],
+    };
+    expect(validateProfile(profile, valid)).toEqual([]);
+  });
+
+  it('rejects an unknown roster class', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [{ class: 'not-a-real-persona', multiplicity: 1 }],
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /not-a-real-persona.*not a known persona class/.test(p))).toBe(
+      true,
+    );
+  });
+
+  it('rejects a reports_to that names a class absent from the roster', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [{ class: 'code', reportsTo: 'coo', multiplicity: 1 }], // coo valid but not in roster
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /reports_to.*not present in this roster/.test(p))).toBe(true);
+  });
+
+  it('rejects a reports_to that is not a known persona class at all', () => {
+    const profile: FleetProfile = {
+      id: 'x',
+      title: 'X',
+      description: 'd',
+      lead: 'ceo',
+      floor: [],
+      roster: [
+        { class: 'ceo', multiplicity: 1 },
+        { class: 'code', reportsTo: 'ghost', multiplicity: 1 },
+      ],
+    };
+    const problems = validateProfile(profile, valid);
+    expect(problems.some((p) => /ghost.*not a known persona class/.test(p))).toBe(true);
+  });
+});
+
+describe('loadProfiles with a temp override dir', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'mosaic-profiles-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('throws when a profile references an unknown class (validated against real roles)', async () => {
+    await writeFile(
+      join(dir, 'bad.yaml'),
+      'id: bad\ntitle: Bad\ndescription: d\nlead: nope-not-real\nroster:\n  - class: nope-not-real\n',
+    );
+    await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
+      /is invalid|not a known persona class/,
+    );
+  });
+
+  it('throws on duplicate profile ids across files', async () => {
+    const body = 'title: Dup\ndescription: d\nlead: ceo\nroster:\n  - class: ceo\n';
+    // Same declared id in two differently-named files -> id mismatches filename
+    // first; use matching filenames+id to force the duplicate-id path instead.
+    await writeFile(join(dir, 'dup.yaml'), `id: dup\n${body}`);
+    await writeFile(join(dir, 'dup.yml'), `id: dup\n${body}`);
+    await expect(loadProfiles({ profilesDir: dir, rolesDir })).rejects.toThrow(
+      /Duplicate profile id/,
+    );
+  });
+});

packages/mosaic/src/commands/fleet-profiles.ts

@@ -0,0 +1,377 @@
+/**
+ * `mosaic fleet profile <list|show>` — system-type profiles (North Star H2).
+ *
+ * A profile is a DECLARATIVE mapping from a "system type" (software-delivery,
+ * personal-assistant, research, business, marketing, …) to a persona roster plus
+ * its org topology. Profiles are DATA, seeded from the framework like roles:
+ *   framework/fleet/profiles/*.yaml  ->  <mosaicHome>/fleet/profiles/*.yaml
+ * so an operator declares a system type and gets the matching roster from the
+ * baseline library with NO code change (NS-9 / AC-NS-6).
+ *
+ * This module loads, parses, and VALIDATES those yaml files. Validation guards
+ * roster/library drift: every persona class a profile references MUST resolve to
+ * a real persona in the role library. Because the library encodes class identity
+ * INLINE in prose (e.g. `` (`class: marketing-lead`) ``) — not YAML frontmatter —
+ * and a few engineering personas (planner/decomposition) carry no marker at all,
+ * the set of valid classes is the UNION of three signals:
+ *   1. inline `` `class: X` `` markers scanned from roles/*.md,
+ *   2. the persona rows in roles/LIBRARY.md (the authoritative index),
+ *   3. the role filenames themselves (roles/<class>.md).
+ * See `listPersonaClasses`.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import type { Command } from 'commander';
+import YAML from 'yaml';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+/** Directory holding the seeded profile yaml files. */
+export function defaultProfilesDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'profiles');
+}
+
+/** Directory holding the persona role contracts. */
+export function defaultRolesDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'roles');
+}
+
+export interface ProfileRosterEntry {
+  class: string;
+  reportsTo?: string;
+  multiplicity: number;
+}
+
+export interface FleetProfile {
+  id: string;
+  title: string;
+  description: string;
+  lead: string;
+  floor: string[];
+  roster: ProfileRosterEntry[];
+  notes?: string;
+}
+
+/**
+ * Extract the set of valid persona classes from the role library.
+ *
+ * Sources (unioned — see module doc for why each is needed):
+ *   1. inline `` `class: X` `` markers in every roles/*.md (the primary signal;
+ *      a marker may wrap across a newline, e.g. `` `class:\n support-agent` ``).
+ *   2. persona-name cells from the LIBRARY.md index tables.
+ *   3. the role filename stems (roles/<class>.md), covering personas whose file
+ *      documents an alias instead of carrying its own marker (planner ->
+ *      orchestrator, decomposition).
+ *
+ * Returns a Set so membership checks in the validator are O(1). Missing dir or
+ * unreadable files degrade gracefully to whatever was found (an empty set makes
+ * the validator reject every class, which surfaces a clear error).
+ */
+export async function listPersonaClasses(rolesDir = defaultRolesDir()): Promise<Set<string>> {
+  const classes = new Set<string>();
+  let entries: string[];
+  try {
+    entries = await readdir(rolesDir);
+  } catch {
+    return classes;
+  }
+  // Match `class: X` even when the value wrapped onto the next line. Allow
+  // surrounding backtick(s); the value is a single kebab-case token.
+  const inlineMarker = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g;
+  // LIBRARY.md persona rows: first table cell is the persona name.
+  const libraryRow = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    let text: string;
+    try {
+      text = await readFile(join(rolesDir, entry), 'utf8');
+    } catch {
+      continue;
+    }
+    if (entry === 'LIBRARY.md') {
+      for (const m of text.matchAll(libraryRow)) {
+        const name = m[1];
+        // Skip the markdown table divider / header artifacts.
+        if (name && name !== 'persona') classes.add(name);
+      }
+      continue;
+    }
+    // Role contract: the filename stem is itself a valid class (covers alias docs).
+    classes.add(basename(entry, '.md'));
+    for (const m of text.matchAll(inlineMarker)) {
+      if (m[1]) classes.add(m[1]);
+    }
+  }
+  return classes;
+}
+
+function asString(value: unknown, ctx: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`profile ${ctx} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+/**
+ * Parse raw yaml text into a typed FleetProfile. Pure (no IO). Throws a
+ * descriptive error on a malformed profile so the loader/CLI fail loudly.
+ * `sourceId` (typically the filename stem) is used only for error messages and
+ * to validate that the declared `id` matches the file it came from.
+ */
+export function parseProfile(rawText: string, sourceId?: string): FleetProfile {
+  const parsed = YAML.parse(rawText) as Record<string, unknown> | null;
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`profile ${sourceId ?? '<?>'} did not parse to a mapping`);
+  }
+
+  const id = asString(parsed['id'], `${sourceId ?? '<?>'}.id`);
+  if (sourceId && id !== sourceId) {
+    throw new Error(`profile id "${id}" does not match its filename "${sourceId}"`);
+  }
+
+  const rawFloor = parsed['floor'] ?? [];
+  if (!Array.isArray(rawFloor)) {
+    throw new Error(`profile ${id}.floor must be an array`);
+  }
+  const floor = rawFloor.map((c, i) => asString(c, `${id}.floor[${i}]`));
+
+  const rawRoster = parsed['roster'];
+  if (!Array.isArray(rawRoster) || rawRoster.length === 0) {
+    throw new Error(`profile ${id}.roster must be a non-empty array`);
+  }
+  const roster: ProfileRosterEntry[] = rawRoster.map((row, i) => {
+    const r = row as Record<string, unknown>;
+    const cls = asString(r?.['class'], `${id}.roster[${i}].class`);
+    const multRaw = r?.['multiplicity'];
+    let multiplicity = 1;
+    if (multRaw !== undefined && multRaw !== null) {
+      if (typeof multRaw !== 'number' || !Number.isInteger(multRaw) || multRaw < 1) {
+        throw new Error(`profile ${id}.roster[${i}].multiplicity must be a positive integer`);
+      }
+      multiplicity = multRaw;
+    }
+    const entry: ProfileRosterEntry = { class: cls, multiplicity };
+    const reportsTo = r?.['reports_to'];
+    if (reportsTo !== undefined && reportsTo !== null) {
+      entry.reportsTo = asString(reportsTo, `${id}.roster[${i}].reports_to`);
+    }
+    return entry;
+  });
+
+  const profile: FleetProfile = {
+    id,
+    title: asString(parsed['title'], `${id}.title`),
+    description: asString(parsed['description'], `${id}.description`),
+    lead: asString(parsed['lead'], `${id}.lead`),
+    floor,
+    roster,
+  };
+  const notes = parsed['notes'];
+  if (notes !== undefined && notes !== null) {
+    profile.notes = asString(notes, `${id}.notes`);
+  }
+  return profile;
+}
+
+/**
+ * Validate a profile against the set of valid persona classes and its own roster.
+ * Returns the list of problems (empty when valid) rather than throwing, so the
+ * loader can aggregate errors across many profiles.
+ *
+ * Checks:
+ *   - lead resolves to a real persona class.
+ *   - every floor[] entry resolves.
+ *   - every roster[].class resolves.
+ *   - every roster[].reports_to resolves AND names a class present in THIS roster
+ *     (topology edges must point at a seat that exists in the profile).
+ * Cycle detection in the reports_to graph is intentionally out of scope.
+ */
+export function validateProfile(profile: FleetProfile, validClasses: Set<string>): string[] {
+  const problems: string[] = [];
+  const rosterClasses = new Set(profile.roster.map((r) => r.class));
+
+  if (!validClasses.has(profile.lead)) {
+    problems.push(`lead "${profile.lead}" is not a known persona class`);
+  }
+  for (const f of profile.floor) {
+    if (!validClasses.has(f)) {
+      problems.push(`floor entry "${f}" is not a known persona class`);
+    }
+  }
+  for (const entry of profile.roster) {
+    if (!validClasses.has(entry.class)) {
+      problems.push(`roster class "${entry.class}" is not a known persona class`);
+    }
+    if (entry.reportsTo !== undefined) {
+      if (!validClasses.has(entry.reportsTo)) {
+        problems.push(
+          `roster "${entry.class}" reports_to "${entry.reportsTo}" is not a known persona class`,
+        );
+      } else if (!rosterClasses.has(entry.reportsTo)) {
+        problems.push(
+          `roster "${entry.class}" reports_to "${entry.reportsTo}" which is not present in this roster`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
+export interface LoadProfilesOptions {
+  /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
+  profilesDir?: string;
+  /** Override the roles dir (tests). Defaults to <mosaicHome>/fleet/roles. */
+  rolesDir?: string;
+  mosaicHome?: string;
+}
+
+function resolveDirs(opts: LoadProfilesOptions): { profilesDir: string; rolesDir: string } {
+  const mosaicHome = opts.mosaicHome ?? defaultMosaicHome();
+  return {
+    profilesDir: opts.profilesDir ?? defaultProfilesDir(mosaicHome),
+    rolesDir: opts.rolesDir ?? defaultRolesDir(mosaicHome),
+  };
+}
+
+/**
+ * Load, parse, and validate every profile yaml in the profiles dir. Throws if
+ * any profile is malformed, references an unknown class, or duplicates an id.
+ * Profiles are returned sorted by id for deterministic output.
+ */
+export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<FleetProfile[]> {
+  const { profilesDir, rolesDir } = resolveDirs(opts);
+  let files: string[];
+  try {
+    files = (await readdir(profilesDir)).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+  } catch {
+    throw new Error(`No fleet profiles directory at ${profilesDir}`);
+  }
+  files.sort();
+
+  const validClasses = await listPersonaClasses(rolesDir);
+  const profiles: FleetProfile[] = [];
+  const seen = new Map<string, string>();
+
+  for (const file of files) {
+    const sourceId = basename(file, file.endsWith('.yaml') ? '.yaml' : '.yml');
+    const rawText = await readFile(join(profilesDir, file), 'utf8');
+    const profile = parseProfile(rawText, sourceId);
+
+    const prior = seen.get(profile.id);
+    if (prior) {
+      throw new Error(`Duplicate profile id "${profile.id}" in ${file} and ${prior}`);
+    }
+    seen.set(profile.id, file);
+
+    const problems = validateProfile(profile, validClasses);
+    if (problems.length > 0) {
+      throw new Error(`Profile ${file} is invalid:\n  - ${problems.join('\n  - ')}`);
+    }
+    profiles.push(profile);
+  }
+  return profiles;
+}
+
+/** Load and validate a single profile by id. Throws if not found. */
+export async function loadProfile(
+  id: string,
+  opts: LoadProfilesOptions = {},
+): Promise<FleetProfile> {
+  const profiles = await loadProfiles(opts);
+  const match = profiles.find((p) => p.id === id);
+  if (!match) {
+    const known = profiles.map((p) => p.id).join(', ') || '(none)';
+    throw new Error(`Unknown profile "${id}". Known profiles: ${known}`);
+  }
+  return match;
+}
+
+/** Total seat count of a roster, honoring multiplicity. */
+function rosterSize(profile: FleetProfile): number {
+  return profile.roster.reduce((sum, entry) => sum + entry.multiplicity, 0);
+}
+
+function printProfileList(profiles: FleetProfile[]): void {
+  if (profiles.length === 0) {
+    console.log('(no profiles)');
+    return;
+  }
+  for (const p of profiles) {
+    console.log(`${p.id}\t${p.title}\tlead=${p.lead}\troster=${rosterSize(p)}`);
+  }
+}
+
+function printProfileShow(profile: FleetProfile): void {
+  console.log(`${profile.id} — ${profile.title}`);
+  console.log(profile.description);
+  console.log('');
+  console.log(`lead: ${profile.lead}`);
+  console.log(`floor: ${profile.floor.join(', ') || '-'}`);
+  console.log(`roster (${rosterSize(profile)} seat(s)):`);
+  for (const entry of profile.roster) {
+    const reports = entry.reportsTo ? ` reports_to=${entry.reportsTo}` : '';
+    const mult = entry.multiplicity > 1 ? ` x${entry.multiplicity}` : '';
+    console.log(`  - ${entry.class}${mult}${reports}`);
+  }
+  if (profile.notes) {
+    console.log('');
+    console.log(`notes: ${profile.notes}`);
+  }
+}
+
+/**
+ * Register `profile` under an existing `fleet` command. `mosaicHomeFor` resolves
+ * the active --mosaic-home (parent flag) at call time, matching the backlog
+ * subcommand wiring. Validation errors exit non-zero with a readable message.
+ */
+export function registerFleetProfileCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const profileCmd = fleetCmd
+    .command('profile')
+    .description('System-type profiles: declarative persona roster + topology (H2)');
+
+  profileCmd
+    .command('list')
+    .description('List available system-type profiles (id, title, lead, roster size)')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        const profiles = await loadProfiles({ mosaicHome: mosaicHomeFor() });
+        if (opts.json) {
+          console.log(JSON.stringify(profiles));
+          return;
+        }
+        printProfileList(profiles);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  profileCmd
+    .command('show <id>')
+    .description('Show a profile: full roster with reports_to/multiplicity, floor, lead')
+    .option('--json', 'Print JSON')
+    .action(async (id: string, opts: { json?: boolean }) => {
+      try {
+        const profile = await loadProfile(id, { mosaicHome: mosaicHomeFor() });
+        if (opts.json) {
+          console.log(JSON.stringify(profile));
+          return;
+        }
+        printProfileShow(profile);
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  return profileCmd;
+}

packages/mosaic/src/commands/fleet.spec.ts

@@ -82,6 +82,7 @@ describe('registerFleetCommand', () => {
       'init',
       'install',
       'install-systemd',
+      'profile',
       'ps',
       'remove',
       'restart',
@@ -92,6 +93,15 @@ describe('registerFleetCommand', () => {
     ]);
   });
 
+  it('registers the profile subcommand with list and show', () => {
+    const program = buildProgram();
+    const fleet = program.commands.find((command) => command.name() === 'fleet');
+    const profile = fleet!.commands.find((command) => command.name() === 'profile');
+
+    expect(profile).toBeDefined();
+    expect(profile!.commands.map((command) => command.name()).sort()).toEqual(['list', 'show']);
+  });
+
   it('registers the backlog subcommand with its operations', () => {
     const program = buildProgram();
     const fleet = program.commands.find((command) => command.name() === 'fleet');

packages/mosaic/src/commands/fleet.ts

@@ -9,6 +9,7 @@ import type { Command } from 'commander';
 import YAML from 'yaml';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
 import { registerFleetBacklogCommand } from './fleet-backlog.js';
+import { registerFleetProfileCommand } from './fleet-profiles.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -1706,6 +1707,10 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
   // fleet/ directory as the roster and heartbeats.
   registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
 
+  // System-type profiles (H2): declarative persona roster + topology, resolved
+  // from <mosaicHome>/fleet/profiles/*.yaml using the same --mosaic-home flag.
+  registerFleetProfileCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
+
   return cmd;
 }