naive-framework 0.0.0-stage → 0.1.0

package/purpose/frameworks/onboarding-handoff-framework.md

@@ -0,0 +1,269 @@
+---
+type: framework
+ai-model: none
+source: human
+created: 2026-05-20T...
+tags: [methodology, consultancy, onboarding, handoff, customer-success]
+related-entities:
+  - "a project note"
+related-frameworks:
+  - "[[business-discovery-framework]]"
+  - "[[post-discovery-deliverable-playbook]]"
+status: living-document
+authored-after: Lauren engagement (2026-05-20)
+---
+
+# Onboarding Handoff Framework
+
+What happens after the deliverable lands with the customer. How they learn what we built. How they graduate from being onboarded to running the methodology themselves. How the consultant supports without becoming a crutch.
+
+This framework is consultant-facing — it describes what *we* do to set the customer up for success. The customer-facing version of this lives in the README.html that ships with every deliverable.
+
+---
+
+## The first 30 days
+
+The customer's first 30 days with the methodology are the *make-or-break window*. If they don't use the vault meaningfully in the first month, they probably never will. This framework structures that window.
+
+### Day 0 — Handoff
+
+The deliverable lands. The customer has:
+- Files on their computer
+- A bootstrap command they haven't run yet
+- A README they may or may not have read
+
+**Consultant action:** within 24 hours, send a brief, warm message acknowledging the handoff. Something like:
+
+> "Sent you the package — let me know when you've had a chance to try the bootstrap. No pressure on timing. The README explains everything; we can troubleshoot together if anything is unclear."
+
+### Day 1-3 — First session
+
+The customer runs the bootstrap command and goes through Session 1 (Welcome & orientation) of the onboarding skill. The onboarding skill handles 95% of this; the consultant's job is to be available for the 5% that goes off-script.
+
+**Common Day 1 friction points:**
+- Bootstrap command can't find the skills package folder → check folder placement
+- Claude doesn't have file access to the vault → check Cowork / Claude Code permissions
+- The CLAUDE.md doesn't get installed correctly → re-run with explicit instructions
+- Customer says "I don't know what to type next" → reference the README's session prompts
+
+**Consultant action:** be available for text the first day. After that, the onboarding skill should carry them.
+
+### Day 4-14 — Articulation work
+
+Customer runs Sessions 2 (BASED) and 3 (SMART). The vault gets its first real content — the customer's actual vision and scope captured in their own words.
+
+**Common Day 4-14 friction points:**
+- Customer's BASED vision feels small (self-censorship) → the skill should catch this; if not, gentle nudge from consultant
+- Customer struggles to convert BASED to SMART → may need a brief call
+- Customer's vault is otherwise empty (they haven't captured anything in `_ideas/`) → not a problem; ideas come naturally with use
+
+**Consultant action:** read what the customer captures (with permission) within 48 hours of session completion. Offer brief reactions. Resist the urge to rewrite their articulations.
+
+### Day 15-21 — Real improvement
+
+Customer runs Session 4 — uses a business skill (client-intake, care-plan-author, monthly-financial-review, social-content-generator, etc.) on something real. This is the **methodology proving itself**.
+
+**Why this session matters most:**
+If the customer feels real value from Session 4, they keep using the methodology. If they don't, the package becomes a relic on their drive.
+
+**Consultant action:** check in after Session 4. Ask: "Was that useful? What would have made it more useful?" Capture their answer — it improves the skill for future customers.
+
+### Day 22-30 — Rhythm
+
+Customer runs Session 5 — establishes their daily / weekly / monthly cadence. Onboarding skill steps back. Customer is now driving.
+
+**Consultant action:** schedule the 30-day check-in conversation. This is the proper handoff moment.
+
+---
+
+## The 30-day check-in
+
+A 30-45 minute conversation, scheduled at handoff for 30 days later. Format:
+
+**What's working?**
+- Which skills did they use?
+- What was easiest?
+- What surfaced that they didn't expect?
+
+**What's not working?**
+- What feels overweight?
+- What did they skip?
+- What's confusing?
+
+**Where to go from here?**
+- Next 30 days — any specific focus?
+- Any additional skills they want?
+- Move from Shape A to Shape B (full vault), or stay light?
+- Support tier going forward?
+
+**Capture:** consultant takes notes in the customer's engagement log (see template below). Notes are also for the consultancy's own learning.
+
+---
+
+## The calendar architecture
+
+Every customer has three potential calendars. Make this explicit during onboarding (Session 5 or follow-up):
+
+| Calendar | What it holds | Lives where |
+|---|---|---|
+| **Personal (master)** | Life events, family, faith, rest, friends, health | Customer's personal Google Calendar |
+| **Business** | Customer's business operations — client visits, team meetings, content sessions | Separate Google Calendar, subscribed-to-from personal view |
+| **Day-job (optional)** | Work commitments for any employer | Separate Google Calendar (if applicable) |
+
+The personal calendar is the master. The others overlay onto it. This way the customer sees their whole life in one place but can mentally separate which life-domain a given block belongs to.
+
+**Consultant action:** during Session 5 or the 30-day check-in, walk the customer through setting up the three-calendar architecture in Google Calendar. ~15 minutes of screen-share. Most customers benefit from this.
+
+---
+
+## The post-onboarding rhythm
+
+After Session 5, the customer should have a sustainable rhythm. Recommend (customizable per customer):
+
+### Daily
+- Capture ideas into `_ideas/` as they happen (1-minute moments, not a chore)
+- Update entity profiles when something material changes
+
+### Weekly (end of week)
+- 5-10 minute SESSION_LOG entry: what got done, what's next
+- Review `_sessions/planned/` to set the next week's focus
+
+### Monthly
+- Run the relevant industry-specific monthly skill (e.g., `monthly-financial-review` for the business)
+- Review `_ideas/` — any ideas ready to graduate to entities?
+
+### Quarterly
+- Cycle close: review the cycle goals, retro on what worked / didn't
+- Set next cycle goals (uses the cycle pattern from methodology)
+
+### Annually
+- Re-articulate BASED + SMART (these aren't fixed; they evolve)
+- Tithe disbursement audit (if applicable — Lauren-specific pattern, generalizable to "annual giving" or "annual generosity")
+- Brand audit (does the brand still match what the business has become?)
+
+---
+
+## Support tiers
+
+Define explicitly with the customer at the 30-day check-in:
+
+| Tier | What it includes | Cost |
+|---|---|---|
+| **Self-serve** | Customer uses methodology independently. Consultant available for text Q&A. | Free / included |
+| **$100 call** | One-off coaching call when stuck. 30-45 min. | $100 |
+| **Monthly check-in retainer** | Recurring monthly session (60 min) — review progress, refine, troubleshoot | TBD ($300-500/mo range, customer-dependent) |
+| **Deep engagement** | Multi-session deeper work — new entity articulation, methodology adaptation, multi-vault setup, custom skill authoring | Project-priced ($1k-15k range, depending on scope) |
+
+**Lauren is currently:** self-serve + text Q&A (free pilot). The 30-day check-in will determine if she upgrades.
+
+---
+
+## The engagement log (consultant-side)
+
+For every customer, the consultant maintains an engagement log. Lives at a project file.
+
+### Template
+
+```yaml
+---
+type: customer-engagement
+customer-name: <full name>
+business-name: <business name>
+business-type: <industry>
+engagement-start: <YYYY-MM-DD>
+engagement-status: active | paused | completed | churned
+deliverable-shape: A | B | C
+support-tier: self-serve | $100-call | retainer | deep
+created: <ISO timestamp>
+last-updated: <ISO timestamp>
+---
+```
+
+### Sections
+
+**Overview**
+- Customer summary (1-2 sentences)
+- Business summary (1-2 sentences)
+- Why they engaged with the consultancy
+
+**Discovery findings**
+- Top 3 things that surfaced
+- Anything notable about how they articulate / their working style
+
+**Deliverable summary**
+- Shape (A/B/C)
+- What was customized
+- Notable methodology amendments authored
+
+**Session log** (newest first)
+- Each session: date, format, what we did, what they learned, what's next
+
+**Wins**
+- Concrete outcomes from using the methodology
+- Customer quotes (with permission, for case studies)
+
+**Friction**
+- What's been hard
+- What we changed in response
+
+**Methodology learnings**
+- What this customer taught us about the methodology / consultancy process
+- Updates we made to frameworks based on this customer
+
+**Financial**
+- Pricing agreed
+- Payments received
+- Outstanding
+
+**Referrals**
+- Customers they've referred
+- Customers they might refer
+
+---
+
+## When the consultant steps back
+
+The onboarding skill is designed to step back after Session 5. The consultant should mirror this — be available, but stop being the active driver.
+
+Signs the customer is *driving themselves*:
+- They're capturing ideas without prompting
+- They're running sessions and logging them
+- They're invoking skills by name
+- They're referring to entity profiles or pillar specs as if they're real working documents
+- They're asking sharper, more methodology-fluent questions
+
+Signs the customer is *not yet self-driving*:
+- They reach out to consultant for things the skills could handle
+- They haven't captured anything new in `_ideas/`
+- The SESSION_LOG hasn't been updated in 2+ weeks
+- They're not invoking skills — just chatting with Claude freely
+- They say "I forgot what to do" or "I'm not sure how this works"
+
+If not self-driving by Day 30: gentle re-engagement. Walk them through the part that didn't land. Update the onboarding skill if a systematic gap surfaces.
+
+---
+
+## Anti-patterns
+
+- ✗ Treating the customer like they need hand-holding forever
+- ✗ Treating the customer like they're on their own after handoff
+- ✗ Skipping the 30-day check-in
+- ✗ Letting the engagement log get stale (it's how we learn)
+- ✗ Not capturing customer wins (no case studies = no referrals)
+- ✗ Selling the customer support they don't actually need
+- ✗ Failing to refine the framework based on what each customer teaches
+
+---
+
+## Companion frameworks
+
+- `business-discovery-framework.md` — the discovery interview structure (Step 1 of the engagement)
+- `post-discovery-deliverable-playbook.md` — what to build (Steps 2-9 of the engagement)
+- This file — what happens after the deliverable lands (Steps 10+)
+- `vault-and-tooling-consultancy-setup.md` — the original consultancy checklist (predates these frameworks; gradually being subsumed)
+
+---
+
+## Living document note
+
+Refine after every customer's 30-day check-in. The framework gets sharper with each engagement.

package/purpose/frameworks/post-discovery-deliverable-playbook.md

@@ -0,0 +1,274 @@
+---
+type: framework
+ai-model: none
+source: human
+created: 2026-05-20T...
+tags: [methodology, consultancy, deliverables, playbook, post-discovery]
+related-entities:
+  - "a project note"
+related-frameworks:
+  - "[[business-discovery-framework]]"
+  - "[[onboarding-handoff-framework]]"
+status: living-document
+authored-after: Lauren engagement (2026-05-20)
+---
+
+# Post-Discovery Deliverable Playbook
+
+What to build after discovery — which deliverable shape for which customer, in what order, with what contents. Authored after the Lauren engagement surfaced the need to triage deliverable shape rather than default to the same one for everyone.
+
+This is a **decision framework**, not a single answer. Different customers get different deliverables based on triage criteria below.
+
+---
+
+## The three deliverable shapes
+
+### Shape A — Lightweight skills package
+
+**~50 KB, ~25 files. Drop-in to customer's existing or empty vault.**
+
+What it contains:
+- 10-12 skills (4 methodology essentials + 6-8 business-specific)
+- 1 onboarding meta-skill (`<customer>-onboarding`)
+- A `CLAUDE-template.md` for vault root
+- README.html with copy-pasteable session prompts
+- Bootstrap command HTML that does file management automatically
+- Methodology starter doc (HTML + MD)
+
+What it's for:
+- Non-technical first-touch customers
+- Customers exploring whether the methodology fits
+- Customers with no existing structured vault
+- Free or low-commitment pilot engagements
+
+What it's NOT for:
+- Customers with substantial existing business documentation that needs migration
+- Customers ready for a populated vault with their actual content organized
+- Engagements where the consultant has time + budget to do file migration
+
+### Shape B — Full populated vault
+
+**~150 MB+ depending on customer files. Complete operator system.**
+
+What it contains:
+- Everything in Shape A, plus:
+- Multi-vault structure (business + personal + optional day-job)
+- Populated entity profiles (BASED + SMART articulated)
+- Spec stack (SERVICE_SPEC, OPERATIONS_SPEC, CLIENT_MODEL_SPEC, CUSTOMER_EXPERIENCE_SPEC, QUALITY_SPEC)
+- Initiatives (3-5) + cycles (2-3)
+- Planned sessions queue
+- Customer's actual business documents migrated to proper pillar locations
+- Session logs (discovery transcript + summary)
+- Document migration checklist
+- Tooling inventory
+
+What it's for:
+- Customers with substantial existing documentation worth migrating
+- Customers with team / multi-city / complex operations
+- Paid engagements where the consultant's time can be invested
+- Customers ready to commit to the methodology fully
+
+What it's NOT for:
+- First-touch non-technical operators (overwhelming)
+- Customers without much existing documentation (nothing to migrate)
+- Quick consultations / spot help
+
+### Shape C — Hybrid (Lightweight first, populate over time)
+
+**Start at Shape A. Customer's vault populates organically through their own methodology sessions.**
+
+The default for most customers. They get Shape A on day one; the vault grows as they articulate entities, capture ideas, log sessions. The consultant may return for "deepening" sessions (folder migration, populated initiatives) as the customer's engagement matures.
+
+What it's for:
+- Most customers, most of the time
+- When in doubt, default to this
+
+---
+
+## Triage decision tree
+
+For each new customer, walk this tree to choose deliverable shape:
+
+```
+Does the customer have substantial existing business documentation
+(>100 pages of docs, multiple folders, established processes)?
+  │
+  ├── YES → Are they technical enough to absorb a full populated vault on day one?
+  │           ├── YES → Shape B (Full Vault)
+  │           └── NO → Shape C (Hybrid — start lightweight)
+  │
+  └── NO → Shape A (Lightweight) is correct
+            └── Consider Shape C if customer signals strong commitment
+                during discovery
+```
+
+Other triage signals:
+
+| Signal | Shape implication |
+|---|---|
+| Free pilot, exploring | A or C |
+| Paid engagement, scoped | B (if docs warrant) or C |
+| Customer says "I'm overwhelmed by my current setup" | A — don't add more |
+| Customer says "I have everything but it's scattered" | B — migration is the value-add |
+| Solo founder, early-stage | A |
+| Team + multiple cities + active operations | B or C |
+| Customer is technical (developer, IT background) | B is more digestible |
+| Customer is non-technical | A or C, with explanatory-mode onboarding |
+| Engagement is < 1 week of consultant time | A |
+| Engagement is > 1 week with deep folder review | B |
+
+## What every deliverable includes (the baseline)
+
+Regardless of Shape A / B / C, every customer deliverable includes:
+
+1. **`CLAUDE.md`** at vault root — the vault constitution
+2. **An onboarding meta-skill** — `<customer>-onboarding` in `_meta/skills/`
+3. **A bootstrap command** (HTML, copy-pasteable) that handles file placement automatically
+4. **A README** (HTML) explaining what's in the package, with 3-5 recommended session prompts
+5. **Methodology starter doc** (HTML + MD) — the simplified methodology reference
+6. **Skills package** (the 10 core skills minimum: BASED, SMART, session-capture, time-awareness + 6 customs)
+7. **Session-log files** from the discovery (transcript + summary if recorded)
+
+The skills + onboarding skill + bootstrap + README make up the **handoff core**. Even in a full Shape-B delivery, these are still the spine.
+
+## Sequencing — from discovery to delivered
+
+Recommended sequence for a customer engagement:
+
+### Step 1 — Pre-discovery folder review (NEW from Lauren retro)
+
+**Before** the discovery call, ask the customer to share or grant access to their current business folder. Skim it. Note:
+- Tools currently in use (from filenames + structure)
+- Documentation that already exists (compliance, training, contracts, plans)
+- Visible gaps
+- Probable industry-specific tools they're using
+
+Use this to:
+- Tailor discovery questions to what you find
+- Avoid asking obvious questions ("do you have an LLC?")
+- Identify what's scattered vs. what's missing
+
+### Step 2 — Discovery session
+
+Use `business-discovery-framework.md`. With the pre-discovery folder review in mind, the discovery becomes much sharper — you're filling gaps, not surveying from zero.
+
+Capture: raw transcript (if recorded) + summary + your own notes.
+
+### Step 3 — Folder deep review (between discovery and build)
+
+Within 24 hours of discovery, do a thorough review of the customer's actual folder. Catalog:
+- Existing assets (compliance, training, plans, financial, marketing, customer records)
+- Tools confirmed in use (from real artifacts)
+- Industry-specific tools surfaced (e.g., PandaDoc, industry CRM)
+- Quality of existing documentation
+- Estimate of migration effort if going Shape B
+
+### Step 4 — Triage decision
+
+Use the decision tree above. Pick A, B, or C. Document the choice + reasoning.
+
+### Step 5 — Methodology adaptation check
+
+Does the customer's business require a methodology amendment? E.g., a service business needs SAD-for-service-businesses; a brick-and-mortar might need new conventions. If yes:
+- Capture the amendment as you build (not retroactively)
+- Reference in the customer's CLAUDE.md
+- Either PROPOSED status (informally tested) or RATIFIED (formally adopted after customer engagement)
+
+### Step 6 — Build the deliverable
+
+Shape A: 1-3 hours
+Shape B: 1-3 days (or more depending on file migration)
+Shape C: Start with Shape A; populate Shape B portions as customer requests over time
+
+### Step 7 — Author the customer's onboarding skill
+
+Tailored to the customer (their name, their business). Uses the explanatory mode pattern. Includes 5-session sequence (Welcome → BASED → SMART → Real improvement → Rhythm).
+
+### Step 8 — Test the bootstrap command
+
+Before sending, paste the bootstrap command into a fresh Claude session pointing at a test copy of the deliverable. Verify Claude correctly:
+- Finds the skills package folder
+- Moves skills to `_meta/skills/`
+- Installs CLAUDE.md
+- Creates `_ideas/` and `_sessions/` folders
+- Invokes the onboarding skill
+
+If anything fails, fix the bootstrap before customer sees it.
+
+### Step 9 — Handoff
+
+Methods (pick based on customer + size):
+- **AirDrop / USB / Direct transfer** — for in-person handoffs (Lauren-shape)
+- **Email** — for sub-25 MB deliverables (Shape A typically)
+- **Google Drive / Dropbox link** — for larger files (Shape B)
+- **Cowork Plugin install** — when we get there (future)
+
+Always include: README + bootstrap command + session logs separately, so customer can read README before unzipping the full package.
+
+### Step 10 — Schedule follow-up
+
+Within 1 week of handoff:
+- Quick check-in (text / brief call): "How did the first session go?"
+- Within 30 days: structured check-in (could be a $100 call per the support tier in the consultancy entity profile)
+
+## Common variations
+
+### Shape A → B upgrade
+
+Customer started on Shape A, then asked for a populated vault later. Process:
+1. Customer's vault is already in working state (Shape A bootstrap completed)
+2. Request access to or copy of their working folder
+3. Do the folder deep review (Step 3 above)
+4. Migrate their content into the existing vault structure (not a new vault)
+5. Add the initiatives, cycles, populated entity profile
+6. Don't disturb their existing work — additive only
+
+### Multi-entity customer
+
+Customer has multiple businesses or projects (not unusual). Recommendation:
+- One vault per entity (per CLAUDE.md guidance)
+- The a consulting practice can deliver Shape A for one and Shape B for another, depending on which entity needs what
+
+### IP-sensitive customer
+
+If the customer's business involves:
+- HIPAA / healthcare
+- Financial data (banking, investing)
+- Legal proceedings
+- Children's data
+
+Then:
+- Stronger boundary on consultant access (screen-share only, time-bounded)
+- Explicit data-handling addendum in the engagement letter (when paid)
+- Document migration may need to skip certain folders
+
+### Day-job customer
+
+Some customers have a day-job they want to operationalize too. Provide the day-job vault scaffold (already in the Lauren package as a recommendation). IP boundaries are critical here — that work is employer-owned.
+
+## Anti-patterns
+
+- ✗ Defaulting to Shape B because that's what we built last time
+- ✗ Skipping the folder review and building before knowing what's already there
+- ✗ Promising a Shape B in scope but only delivering Shape A polish
+- ✗ Authoring methodology amendments retroactively after delivery
+- ✗ Sending the deliverable without testing the bootstrap command on a fresh Claude session first
+- ✗ Forgetting the customer's own files in the deliverable (Shape B specifically)
+- ✗ Making the customer manually place skills somewhere because the bootstrap was vague
+
+## What's deliberately not in this playbook
+
+- Pricing structure — covered separately in the consultancy entity's business pillar
+- Customer acquisition — covered in the marketing strategy (when authored)
+- Skill catalog management — covered in skills documentation
+- The full SAD methodology — covered in `SAD_SKILL_v3.md`
+
+## Living document note
+
+After every customer engagement, return to this playbook and refine. Customer #2 will teach us things customer #1 (Lauren) didn't.
+
+## Companion frameworks
+
+- `business-discovery-framework.md` — the discovery interview structure
+- `onboarding-handoff-framework.md` — what happens once the deliverable lands with the customer
+- `vault-and-tooling-consultancy-setup.md` — the original consultancy checklist (predates this playbook; this playbook subsumes the deliverable-build portions)

package/purpose/frameworks/product-anatomy/README.md

@@ -0,0 +1,63 @@
+---
+type: framework
+source: hybrid
+created: 2026-10-26T22:55:00Z
+ai-model: claude-opus-5.5
+tags: [everything-ecosystem, purpose, product-anatomy, succession-matrix, typesafe, jev]
+description: "Product Anatomy Matrix: fix the venture's core product first, judge every product against it with typed questions (Jev plus a reasoning model), then deduce each product's portfolio role per phase with the Succession Matrix. Version 0.2.0, unevaluated."
+---
+
+# Product Anatomy Matrix
+
+Version 0.2.0 (unevaluated). Nouns follow `docs/ontology.md`; phases and gates follow EE-012, with sources in `purpose/references/references.json`. Research and reasoning: the Claude Doc "Core product framework: research and proposal" (https://claude.ai/artifact/A8e5fEBS3AsszAB2iaBKvd).
+
+## Order
+
+1. **Core product first.** The venture states its core product (`core` in `venture.json`) before any product is ranked. It is required once the venture leaves Discovery. That means four things:
+   - the **promise**: what a person can claim from the venture
+   - **who it is made to**
+   - **what it must not deliver**
+   - the **core competence** that makes the promise deliverable
+
+   No product can be the flagship until this exists, because the flagship is the product that best delivers the core promise.
+2. **Product cards.** Each product is a card in the venture's `products/` folder (`schema/product.schema.json`): name, description, market, job, technology, offering, business model, and `flows_to`.
+3. **Judge every product against the core.** `questions.json` holds seven typed judgments per product. Three are about the core: promise delivery, competence draw, and promise breach. Four are about the phase: job intensity, readiness, revenue and reversibility. Jev answers them all in one request. A reasoning model frames the input and writes the reasons. Spillover is computed from the cards' `flows_to`, not asked.
+4. **Succession Matrix.** `phases.json` sets the venture phases (Discovery, Validation, Beachhead, Scale, Platform), the gate for leaving each, and the weights. Discovery has no weights, because nothing is ranked before the core exists. For each phase, the runner:
+   - checks the flagship must-holds in code: allowed in the phase, delivers at least part of the promise directly, and does not risk breaching it
+   - ranks the products that pass
+   - assigns portfolio roles: flagship, substrate, revenue engine, wedge, option, end product, or unassigned. Wedge keeps its business meaning: the narrow product used to enter a market.
+   - names the successor when the flagship changes between phases
+
+   Near-ties (within 0.1) are reported as ties. Changing a weight never needs re-scoring.
+5. **Re-answer at each gate** (problem-solution fit, product-market fit, repeatability, market leadership). Later phases are projections from today's answers until they are re-scored.
+
+## Run
+
+```bash
+node anatomy.mjs request ../../../schema/examples/workspace/ventures/studio   # a venture folder
+node anatomy.mjs request examples/polity.json                    # or a single input file
+node anatomy.mjs score examples/polity.json out.json --send      # Jev; needs TYPESAFE_API_KEY
+node anatomy.mjs matrix examples/polity.json examples/polity.answers.reasoned.json
+```
+
+Without a key, a reasoning model fills the answers file by hand and names itself in `scorer`. `examples/polity.answers.reasoned.json` is that kind of draft.
+
+## JSON output
+
+`node anatomy.mjs matrix <venture> <answers.json> --json` prints the same matrix as data (assignment A-001), for tests and agents:
+
+```json
+{
+  "venture": "id", "phase": "discovery", "scorer": "who filled the answers",
+  "substrate": "product id or null",
+  "phases": [
+    { "id": "validation", "name": "Validation", "projection": true,
+      "flagship": "product id or null", "tied": ["product id"], "successor": "product id or null",
+      "roles": { "product id": { "roles": ["flagship", "substrate"] }, "other id": { "roles": ["option"], "allowed_from": "beachhead" } },
+      "role_text": { "product id": "flagship + substrate" },
+      "scores": { "product id": { "score": 0.84, "flagship_fails": [] } } }
+  ]
+}
+```
+
+`roles` holds role ids (flagship, substrate, revenue-engine, wedge, end-product, option, unassigned), with `revenue_engine_tied` and `allowed_from` where they apply; `role_text` holds the words the Markdown shows. `test.mjs` checks that the two agree.