Framework Management 🛠️

Understand the Framework Library

The framework library lists every scoring framework — the system FORTIS framework plus any firm-owned custom frameworks. This guide covers the library view. 💡 Tip — Who can use this For platform admins, under Frameworks. Quick reference | Step | Action | |------|--------| | 1 | Browse frameworks and open one to edit or view | Step 1 — Browse the library Go to Frameworks to see every framework template across all firms plus the system FORTIS framework. Each shows its name, owner (System or a firm), pillar count, visibility (Public/Private), and an Edit or View link. System frameworks (owned by a system firm) are admin-editable. Firm-owned frameworks are view-only for admins (the firm owns them). 📝 Note — The library is platform-wide This view shows all frameworks across all firms, unlike a firm's own library (which shows only that firm's frameworks). It's your overview of the scoring models in use platform-wide. 💡 Tip — Open FORTIS to edit the system framework The FORTIS framework is the system default used by most clients. Open it to edit its pillars, metrics, and flag rules — changes affect every client scored under FORTIS (with a material-change confirmation).

Open a Framework in the Editor

Opening a system framework in the editor lets you adjust its pillars, metrics, and flag rules. This guide covers opening and editing. 💡 Tip — Who can use this For platform admins, opening a system-owned framework. Quick reference | Step | Action | |------|--------| | 1 | Open a system framework to edit | Step 1 — Open the editor From the Frameworks list, click Edit on a system-owned framework (like FORTIS). The editor opens. Firm-owned frameworks show a view-only banner and can't be edited — the API defends this with a 403. The "seal" on system frameworks has been lifted, so admins can edit metrics and flag rules end-to-end, not just pillar weights. 📝 Note — Editability is data-driven A framework owned by a system firm (is_system = true) is admin-editable. A firm-owned framework is view-only. The distinction is automatic based on ownership. 💡 Tip — Start with FORTIS If you need to adjust scoring, the FORTIS framework is the one most clients use. Editing it affects the broadest set of clients — review the material-change confirmation carefully before saving.

Add, Reorder & Weight Pillars (Framework Editor)

The framework editor lets you shape how clients are scored by managing pillars — their names, weights, order, and descriptions. System frameworks (like FORTIS) are admin-editable. This guide covers pillar management. 💡 Tip — Who can use this For platform admins, on a system framework's editor page. Quick reference | Step | Action | |------|--------| | 1 | Add, reorder, and weight pillars (must total 100%) | Step 1 — Manage pillars Open a framework in the editor. The pillar management area lets you: - Add a new pillar. - Remove a pillar you no longer want. - Reorder pillars (move up/down). - Edit each pillar's name and default weight. - Edit each pillar's Description and "What healthy looks like" text (these flow to the client dashboard and AI prompts). - Set per-tier weight overrides (collapsed per tier) so pillars can count differently for clients on different plans. A "Total Weight" badge shows the sum of pillar weights — it must hit exactly 100% before you can save. If it doesn't, adjust the weights until it does. 📝 Note — Material changes trigger a confirmation If your pillar changes are material (adding/removing pillars, changing weights), saving triggers a confirmation modal showing how many client workspaces are affected. Cosmetic edits (like fixing a description) save without the prompt. 💡 Tip — Weights reflect strategic priority Pillar weights express how much each area matters to overall health. Higher tiers often rebalance weights toward forward-looking pillars (Transformation, Intelligence). Think deliberately about the weighting — it directly shapes every client's composite score.

Edit Pillar Descriptions & "What Healthy Looks Like"

Each pillar has descriptive text — a description and a "what healthy looks like" primer — that appears on client dashboards and in AI prompts. This guide covers editing them. 💡 Tip — Who can use this For platform admins, in the framework editor. Quick reference | Step | Action | |------|--------| | 1 | Edit a pillar's description and healthy-looks-like text | Step 1 — Edit pillar primers In the framework editor, each pillar has Description and What healthy looks like textareas. These flow to the client dashboard (shown when a client opens a pillar) and to the AI prompts (so Pulse AI understands the pillar's intent). Edit the text to clarify what a pillar measures and what a healthy state looks like. These are cosmetic/informational changes — they save without the material-change confirmation. 📝 Note — Primers shape the AI's understanding The primer text is part of what Pulse AI reads when generating deep-dives and advisory drafts. Clear, accurate primers produce better AI output, so invest in writing them well. 💡 Tip — Write for the client The description and healthy-looks-like text are shown directly to clients. Write them in plain, encouraging language a business owner understands — avoid jargon.

Configure Pillar Metrics

For generic (data-driven) pillars, you configure which metrics drive the pillar and their weights. This guide covers metric configuration. 💡 Tip — Who can use this For platform admins, in the framework editor (generic pillars). Quick reference | Step | Action | |------|--------| | 1 | Add/remove metrics per pillar and set their weights | Step 1 — Configure metrics In the framework editor, each generic pillar has a Metrics section. Add or remove metric rows, each with: - A metric dropdown (filtered to scoreable keys). - A weight for that metric within the pillar. - A required checkbox. - A gated by selector. Metric weights should sum to 100% — an inline warning appears if they don't. For the three FORTIS bespoke pillars (Focus, Transformation, Systems), the metrics section is informational only — it shows the hard-coded recipe (e.g. "60% Rocks on-track + 40% Revenue targets") rather than editable rows. 📝 Note — Metrics are material changes Adding, removing, or reweighting metrics is a material change that triggers the confirmation modal showing affected clients. Cosmetic edits (like a description) don't. 💡 Tip — Keep metric weights balanced A single metric dominating a pillar's weight makes the pillar score volatile to that one input. Balance weights so no single metric overwhelms the pillar.

Configure Flag Rules (Thresholds)

Flag rules define when a metric raises a diagnostic flag — the amber and red thresholds that tell clients and partners something needs attention. You configure these per pillar in the framework editor. This guide covers flag rule configuration. 💡 Tip — Who can use this For platform admins, in a system framework's editor. Quick reference | Step | Action | |------|--------| | 1 | Add or edit flag rules per pillar | Step 1 — Configure flag rules In the framework editor, each pillar has a Flag Rules section. Each rule defines: - The metric it watches (chosen from scoreable keys). - The amber threshold — the value at which a "watch" flag is raised. - The red threshold — the value at which an "act now" flag is raised. - The direction — whether the flag triggers when the metric is below (e.g. margin) or above (e.g. churn) the threshold. - The benchmark reference value. - The unit and a commentary string shown on the client dashboard when the flag fires. You can add new rules or remove existing ones per pillar. 📝 Note — Rules drive the flags clients see These rules are what produce the amber and red flags on client dashboards. A rule with a poorly-set threshold will either cry wolf (too sensitive) or miss real issues (too lenient). Tune them based on what's genuinely concerning for each metric. 💡 Tip — Direction matters Most health metrics flag when they drop below a threshold (lower is worse). But metrics like churn, attrition, or time-to-fill flag when they rise above a threshold (higher is worse). Double-check the direction when you create a rule — a reversed direction will silently suppress real flags.

Set Per-Tier Weight Overrides

Each pillar has a default weight, but you can override how much it counts for clients on different tiers. This guide covers tier weight overrides. 💡 Tip — Who can use this For platform admins, in the framework editor (per pillar). Quick reference | Step | Action | |------|--------| | 1 | Set weight overrides per tier for each pillar | Step 1 — Set tier overrides In the framework editor, each pillar has a collapsed Per-tier weight overrides section (disabled for unsaved/new pillars). Expand it to set how much that pillar counts for each of the five tiers: trial, pulse_ai, access, partner, and executive. This lets you rebalance the composite for higher tiers — for example, putting more weight on Transformation and Intelligence for Executive clients, reflecting a more forward-looking strategic focus. 📝 Note — Overrides are per-pillar, per-tier You set an override for each pillar independently. A pillar with no override uses its default weight for all tiers. The total across pillars must still reach 100% for each tier. 💡 Tip — Reflect strategic emphasis in overrides Tier overrides express how much each pillar should matter at different engagement levels. Higher tiers often warrant more weight on forward-looking pillars. Think about what "executive-level" advisory should emphasize and weight accordingly.

Understand the Material-Change Confirmation

When you save framework edits that materially change scoring, a blocking modal lists each change and how many clients are affected before you can proceed. This guide explains it. 💡 Tip — Who can use this For platform admins, in the framework editor on save. Quick reference | Step | Action | |------|--------| | 1 | Review the material changes and confirm | Step 1 — Review and confirm material changes When you save framework edits, the editor first posts the payload to a preview endpoint. If the diff returns non-empty material changes (added/removed pillars, changed weights, new/removed metrics or flag rules), a blocking modal appears. It lists each change path and the number of affected client workspaces, and requires Confirm & Save to proceed. Cosmetic-only edits (description fixes, primer text) save with no popup. 📝 Note — The PUT re-runs its own diff After you confirm, the actual save (PUT) re-runs the diff independently to write a version-log entry if the change was material. This is best-effort auditing. 💡 Tip — Read the affected-client count The number of affected workspaces tells you the blast radius of your change. A change affecting hundreds of clients deserves more deliberation than one affecting a handful. If unsure, test on a copy or consult before confirming.

System vs Firm-Owned Frameworks

Frameworks are owned either by the system (admin-editable) or by a firm (view-only for admins). This guide explains the distinction. 💡 Tip — Who can use this For platform admins managing frameworks. Quick reference | Owner | Editable? | |-------|-----------| | System (is_system firm) | Yes, by admins | | A regular firm | View-only for admins | The two ownership types System frameworks (like FORTIS) are owned by a "system" firm (is_system = true). They're the platform-wide defaults, and platform admins can edit them fully — pillars, metrics, flag rules, weights, and primers. Firm-owned frameworks are created and owned by a specific advisory firm for their methodology. Admins can view them (to see what a firm is using) but cannot edit them — the firm owns and controls their framework. The API returns a 403 if an admin attempts a firm-owned edit (defense-in-depth). 📝 Note — Editability follows ownership There's no separate "editable" flag — editability is purely a function of which firm owns the framework. System firm = admin-editable; regular firm = firm-editable, admin-view-only. 💡 Tip — Let firms own their methodology Firm-owned frameworks let each advisory firm tailor scoring to their methodology without affecting other firms or the system default. Encourage firms that want a custom approach to create their own rather than editing FORTIS.