Material Master

User Guide v3.8 · TWMD Platform · Internal use only · Updated after Release 65D-A (Navigation & Terminology Alignment)

Material Master is the platform that connects what you buy from suppliers to what your formulas actually require. This guide explains what the platform does, what your role is, and how to use each part of the workspace. No engineering background required.

1. What is Material Master?

Your purchasing system (Wherefour) records what you buy: "Ashwagandha Root Extract — Vendor A — $14.50/kg." It answers what did we buy and from whom?

Material Master answers a different question: what must this material actually be? When your formula requires Ashwagandha Root Extract standardized to 5% Withanolides, that is a specification — not a vendor item. Multiple vendors can supply the same specification. Material Master makes that relationship permanent, searchable, and auditable.

What it does for SNL

Formula integrity — formulas reference specifications, not specific vendors. Sourcing decisions can change without breaking the formula.
Compliance readiness — every canonical specification carries the quality and certification requirements needed for 21 CFR Part 111 documentation.
Procurement intelligence — when two vendors supply the same specification, procurement can compare pricing, lead times, and qualification status directly.
Coverage tracking — the platform shows exactly which portion of the purchase catalog has been mapped to verified specifications.

One sentence: Material Master maps "what you buy" to "what your formulas require," and tracks how far along that mapping is.

When a formula requires "Ashwagandha Root Extract 5% Withanolides," that is a specification — not a vendor line item. Multiple suppliers can provide the same specification. The Material Master makes that relationship explicit and searchable.

How the system works

The intelligence engine analyzes 1,670 supplier materials from the Wherefour inventory catalog and proposes matches to canonical materials, forms, and specifications already defined in the library. The engine recommends; the steward approves. No link is created without human review.

Core principle: The system suggests. You decide. Every approved link creates a permanent relationship used in formulations, procurement, and compliance. Approvals are auditable and irreversible by design.

2. The Canonical Hierarchy

Everything in Material Master is organized into a four-level hierarchy. Understanding this is the most important concept in the platform. Every action you take fits into this structure.

Material
│ What it IS — the substance identity
↓
Material Form
│ How it presents physically or chemically
↓
Material Specification
│ What grade — the quality and procurement boundary
↓
Supplier Material
Who supplies this specification and at what commercial terms

Practical example

Ashwagandha — full hierarchy

MaterialAshwagandha (MAT-0001)

FormRoot Extract (MF-0001)

SpecificationRoot Extract 5% Withanolides (MAT-SPEC-0001)

Supplier MaterialSOURCE-0188 · Shaanxi Hongda · KSM-66® · $12.50/kg

Magnesium — multiple forms and specifications

MaterialMagnesium (MAT-0019)

FormsGlycinate · Citrate · Taurate · Oxide · Malate · L-Threonate

Specification (Glycinate)Magnesium Glycinate (MAT-SPEC-0037)

Specification (Citrate)Magnesium Citrate (MAT-SPEC-0038)

Key rule: Formulas and BOMs reference Material Specifications — not specific suppliers. Multiple suppliers can qualify to deliver the same specification. Supplier selection is a procurement decision, not a formulation decision.

Why this matters in practice

Your Wherefour catalog has 1,670 supplier materials. Most are ingredients with many overlapping names across vendors. "Ashwagandha KSM-66," "Ashwagandha Root Extract 5%," "Shoden® Ashwagandha" and "Ashwagandha (Withania somnifera)" are all different supplier item names for materials that should link to the same canonical specification. Material Master maps all of them correctly.

Current library size

Materials171 canonical materials (MAT-0001 → MAT-0171)

Material Forms344 forms (MF-0001 → MF-0344)

Specifications89 specifications (MAT-SPEC-0001 → MAT-SPEC-0089)

Synonyms / Trade Names483 registered aliases

Supplier Materials1,670 records (918 ingredient · 718 packaging · 34 branded)

3. Platform Workflow

Here is how the platform works from start to finish. As a steward, your main work is in steps 3 and 4.

Supplier materials arrive automatically. Wherefour syncs your purchasing catalog into Material Master every 30 minutes. Each unique item from each vendor appears as a Supplier Material (SM). You have 1,670 SMs across ingredient, packaging, and branded categories.
The intelligence engine evaluates each SM. The engine reads each supplier item name, extracts signals (synonyms, botanical names, potency values, form type keywords), and matches them against the canonical library. It generates a ranked list of candidate canonical matches for each SM, scored 0–100. No link is created automatically.
You review the recommendations. Open the Intelligence tab. The engine's recommendations appear as a queue. Each item shows the proposed match with the evidence that drove the score. You decide whether the match is correct.
You approve, skip, or reject each recommendation. Approving creates a permanent link between the supplier material and the canonical specification. Skipping returns the item to the queue for later. Rejecting marks this specific match as wrong.
Coverage improves. Each approved link increases the coverage percentage shown on the Command Center. More linked SMs means better formulation intelligence, procurement analytics, and compliance readiness.

You are always in control. The engine recommends. You decide. No link is ever created without a steward's explicit approval. All decisions are permanently logged with your email address and timestamp.

4. The Steward Role

A material steward is the person who reviews intelligence recommendations and decides whether supplier materials map correctly to canonical specifications. This is you.

What you do in a typical session

Open Material Master. Go to the Command Center. Check the Start Here panel to see current coverage and the recommended next action.
If the Fast Lane shows "Ready For Approval" candidates — click Review Now. These are the highest-confidence matches and take the least time per item.
Work through the queue using Approve & Next, Skip & Next, or Reject & Next. The keyboard shortcut A approves and advances in one keystroke.
For items you are unsure about — always choose Skip & Next. It is always safe to come back later. Never approve if you are not certain.
When you finish — check the Command Center to see the updated coverage percentage.

How often should you do this?

Regular short sessions are more effective than infrequent long ones. A 15-minute session reviewing the "Ready For Approval" queue (typically 20–60 items) will have measurable impact on coverage. Run the intelligence engine first if new library seeds have been applied.

Best practice: Start each session at the Command Center. Read the Next Best Actions panel. Work the Fast Lane first. Then move to Needs Review. Leave Needs Research for dedicated investigation sessions.

5. Common Actions

These are the four decisions you make for every supplier material in the queue.

Action	Plain meaning	When to use it
Approve & Next	Yes — this vendor item is correctly matched to this specification.	The "Why this was matched" evidence makes sense. The canonical path (Material → Form → Specification) accurately represents what you are buying. You are confident.
Skip & Next	Not sure — come back to this one later.	The match looks plausible but you are not certain. The item is a blend. You need to verify something externally. You want to focus on other items first. Always safe to use.
Reject & Next	No — this specific recommendation is wrong.	The proposed canonical match is clearly incorrect for this supplier item. Rejecting this candidate keeps the SM in the queue for future matches (from engine re-runs with expanded library).
Exclude SM	This item should never be matched.	The supplier material is not a canonical ingredient at all — e.g., it is water, packaging waste, a test sample, or a blend with no appropriate single-material mapping. Removes the SM from active queues permanently.

Approve is permanent. Every approval creates a link that appears in formulations, procurement reports, and compliance records. There is no undo button for a human. If you approved something incorrectly, contact the TWMD engineering team for an administrative correction.

The Approval States (A / B / C / D)

When you click Approve & Next, what happens next depends on how precisely the intelligence engine matched the item:

State	What it means	What happens
State A	Engine matched to a specific Specification	One click → immediate approval → advance to next item. Fastest path.
State B	Engine matched to a Form, and only one Specification exists for that Form	Click → system auto-selects the single spec → Confirm.
State C	Engine matched to a Form, and multiple Specifications exist	Click → a dropdown appears → select the correct grade → Confirm.
State D	Engine matched to a Form, but no Specifications exist yet for that Form	Redirected to Full Review → create the specification inline → then approve.

Keyboard shortcuts

With a workbench item open, these shortcuts work when no text field is active:

AApprove & Next — approve and advance immediately

SSkip & Next — skip without action, move to next

RReject & Next — open rejection panel, then advance

NNext — advance without any counter increment

EscClose any open panel

6. Understanding Intelligence

The intelligence engine is the system that looks at each supplier item name and proposes a canonical match. It uses text analysis — no AI, no machine learning. Every recommendation is traceable to specific signals.

How the engine works

Reads the supplier item name — e.g., "KSM-66 Ashwagandha Root Extract 5% Withanolides"
Extracts signals — trade name "KSM-66", botanical reference "Ashwagandha", source part "Root", extract type "Extract", potency "5%", marker "Withanolides"
Matches against the library — 171 materials, 344 forms, 89 specs, 483 synonyms
Scores each match — stronger, more specific signals give higher scores (capped at 100)
Presents top candidates — ranked by score; highest-scored match is shown first in the workbench

What the score means

Ready (75+)Multiple strong signals fired. Engine is highly confident. Usually safe to approve after verifying the canonical path.

Needs Review (45–74)Good signal coverage but not definitive. Verify the "Why this was matched" evidence before approving.

Needs Research (20–44)Weak signals — typically one partial name match. Research manually before approving. Skip if unsure.

"Why this was matched" — reading the evidence

Every candidate in the workbench shows named signals with point values. Use these to verify the match:

Exact trade name+40 pts — strongest synonym signal. Very reliable.

Botanical source match+35 pts — genus/species name extracted from item, matched to form source.

Form name found in text+30 pts — canonical form name appears as a word in the supplier item name.

Material name in text+20 pts — material name found as a substring. Less specific than form name match.

Extract ratio matched+8 pts — "4:1" or "10:1" matches canonical spec's extract ratio.

Potency matched+7 pts — % in item name within ±5% of canonical spec's potency value.

High Confidence Fast Lane

When Ready For Approval candidates exist, a green hero card appears at the top of the Intelligence tab. Click Review Now → to open that queue directly. Using keyboard shortcuts (A, S, N), an experienced steward can process 30–60 of these in under 15 minutes.

When to re-run the engine

Re-run the intelligence engine (Ingredient domain) after:

New canonical library seeds have been applied (new materials or synonyms added)
New specifications have been created during curation sessions
A library governance correction has been applied

Go to the Intelligence tab → click Run Engine… → select Ingredient → click Dry Run (preview) → then Execute.

Re-running the engine is always safe. It replaces suggested candidates but never touches approved or rejected records.

7. Ingredient Governance Lifecycle

Material Master is built around an ingredient governance hierarchy. Every ingredient object belongs to one of the following tiers, each with a distinct owner and purpose:

Material — What is it? — Owner: Master Data
↓
Form — What type is it? — Owner: Master Data + R&D
↓
Ingredient Specification — What standard do we require? — Owner: R&D (primary)
↓
Supplier Specification — What does the supplier claim? — Owner: Supplier [FUTURE]
↓
Supplier Material — What can we buy? — Owner: Purchasing
↓
Quality Verification — Did the received material meet the requirement? — Owner: Compliance/Quality [FUTURE]

What "future" means: Supplier Specification and Quality Verification are planned governance layers. The current platform implements Material, Form, Ingredient Specification, and Supplier Material. Future releases will add supplier-claimed standards and lot-level verification.

Ownership model

Layer	Owner	Used by	Status
Material	Master Data Steward	All teams	✅ Live
Form	Master Data + R&D	All teams	✅ Live
Ingredient Specification	R&D (primary), Regulatory, Quality	Formulation, Regulatory, Quality, Estimating, Sourcing	✅ Live
Supplier Specification	Supplier	Sourcing, Quality	🔜 Future
Supplier Material	Purchasing	All teams	✅ Live
Quality Verification	Compliance / Quality	Compliance, Quality, Regulatory	🔜 Future

Formula relationship

Formulas consume Ingredient Specifications — not Supplier Materials. This is one of the most important architectural principles in Material Master.

When a formula requires "Ashwagandha Root Extract 5% Withanolides," that is an Ingredient Specification — the R&D-governed standard. Multiple suppliers can deliver materials that satisfy that standard. The formula references the standard; Sourcing finds suppliers who can meet it.

Target formula relationship

FormulaProduct X · Version 2.1

Formula ComponentAshwagandha · 300mg per serving

→ Ingredient SpecificationRoot Extract 5% Withanolides [MAT-SPEC-0001] ← governed standard

→ Supplier Material AKSM-66 · Supplier A · satisfies the standard

→ Supplier Material BSensoril · Supplier B · also satisfies the standard

Why this matters: If Supplier A discontinues their product, the formula doesn't change — Sourcing finds a different Supplier Material that satisfies the same Ingredient Specification. The R&D-governed standard is the stable anchor; supplier selection is a procurement decision.

8. Understanding Coverage

What coverage means

Coverage % = the percentage of supplier materials that have been approved and linked to a canonical specification. With 1,670 total supplier materials:

Coverage 3%~50 SMs linked. Platform is in early stewardship phase.

Coverage 25%~418 SMs linked. Meaningful formulation and procurement intelligence available.

Coverage 50%~835 SMs linked. Substantial operational value. Half the catalog is governed.

Coverage 80%+~1,336+ SMs linked. Near-complete catalog governance.

The three states in the coverage bar

Green — Linked: Approved. Connected to a specification. Used in formulations and reports.
Blue — Has Candidates: Intelligence engine found a match. Awaiting steward approval. In your queue.
Grey — Unmatched: No candidate generated. Usually a library gap (ingredient not in canonical library yet) or a complex blend.

Unmatched does not mean the data is wrong

An unmatched supplier material is not an error. It usually means the canonical library doesn't yet contain that ingredient category. Check the Library Gap Explorer on the Command Center — it shows which categories (botanical extracts, flavors, specialty compounds) are driving the unmatched pool.

Fastest paths to coverage improvement

Approve the Fast Lane — 58 Ready For Approval items are the quickest wins.
Work the Opportunity Center — Materials at the top have the most supplier items waiting. One approval on a top-ranked material may link 20+ SMs.
Run the engine after library expansions — each new seed adds materials that unlock new matches.

9. Ingredient Specifications

Definition: An Ingredient Specification is an R&D-governed ingredient standard that defines the approved identity, potency, composition, regulatory requirements, certifications, and quality expectations for use in formulations. Ingredient Specifications are owned by R&D and used by Formulation, Regulatory, Quality, Estimating, and Sourcing.

Why Ingredient Specifications exist

Materials and Forms tell you what an ingredient is and what type it is. Ingredient Specifications tell you exactly what the ingredient must be to meet your formulation, compliance, and sourcing requirements. They are the bridge between "what ingredient we intend to use" and "which supplier materials can fulfill that intent."

Supplier materials are approved against Ingredient Specifications — not against Materials or Forms directly. Multiple supplier materials from different vendors can satisfy the same Ingredient Specification.

The value chain

Every ingredient decision follows this progression

Material"What is it?" — Ashwagandha (MAT-0001)

Form"What type?" — Ashwagandha Root Extract (MF-0001)

Ingredient Specification"What standard?" — Root Extract 5% Withanolides (MAT-SPEC-0001)

Supplier Material"Who supplies it?" — SOURCE-0042, Vendor A, $14.50/kg

Lifecycle maturity — where each object is used

Stage	Objects used	Question answered
Estimating & Early R&D	Materials & Forms	"Can we make this? What ingredient categories would we use?"
R&D & Compliance	Ingredient Specifications	"What exactly do we require — potency, purity, grade, certifications?"
Sourcing	Approved Supplier Materials	"Who can supply this specification, at what price and lead time?"

Practical implication: You can estimate formula costs using Materials and Forms before any Ingredient Specifications exist. Specifications only become required when moving from estimation to actual formulation development, compliance documentation, or supplier qualification.

Examples of ingredient specifications

Ashwagandha Root Extract 5% WithanolidesKSM-66 and Sensoril-grade items link here. Potency + marker compound defined.

Magnesium Glycinate (no potency grade)Form-level standard — appropriate for commodity Mg glycinate. No potency grade specified yet.

Vitamin C Ascorbic Acid Food GradeGrade-specific — distinguishes from pharmaceutical USP grade.

Bromelain PowderActivity-grade specs (2400 GDU/g, 600 GDU/g) created demand-driven during stewardship.

When no ingredient specification exists yet (State D)

If a supplier item matches a Form but no Ingredient Specification exists, the Governance Queue shows State D. You can create the specification inline via Full Review, or create it first in the Ingredient Specification Explorer tab then return to the queue. Either way, you do not need to leave the platform.

Ingredient Specification Explorer tab

The Ingredient Specs tab shows all 89 active ingredient specifications in a split-pane view. Left pane: searchable, filterable list. Right pane: structured detail view showing potency, botanical identity, certifications, and grade. Use this to verify that a specification with the right quality standard already exists before creating a new one.

Future direction

Ingredient Specifications are expected to become the primary ingredient object assigned to formulation records. Supplier Materials will satisfy Ingredient Specifications — confirming which vendors can deliver which approved standards. This will make the Material Master the authoritative source for both formulation ingredient requirements and supplier qualification status.

Governance rule: Ingredient Specifications are created demand-driven. Only create a new specification when a real supplier material requires it. Do not pre-create specifications for grades that have no supplier items yet.

10. Business Workflows

Different business functions use different layers of the ingredient governance hierarchy. Understanding which layer each function needs helps you prioritize stewardship work.

Function	Primary objects used	Key question	Benefit of governance
Opportunity / Estimating	Materials, Forms	"Can we make this product? What ingredient categories would we need?"	Can estimate formulas before specifications exist. Materials and Forms provide the ingredient framework for early cost modeling.
R&D / Formulation	Ingredient Specifications	"What exactly do we require — potency, grade, botanical source, certifications?"	Ingredient Specifications lock down the R&D-governed standard. Multiple suppliers can qualify against the same specification. Formulas reference specs, not supplier-specific items.
Sourcing	Ingredient Specifications + Supplier Materials	"Who can supply this specification? At what price and lead time?"	Approved Supplier Materials are confirmed against the canonical Material/Form hierarchy. Future Supplier Specification layer will compare supplier-claimed standards against R&D requirements.
Purchasing	Supplier Materials	"What can we buy from which vendor at what price?"	Supplier Materials linked to specifications make procurement decisions traceable to the ingredient standard. Purchase orders can reference governed specifications.
Compliance / Quality	Ingredient Specifications (+ future Quality Verification)	"Did the received material actually meet the specification requirement?"	Ingredient Specifications define the standard against which incoming lots will be verified. Future Quality Verification layer will compare actual COA results against the standard.

Practical implication for stewards: Every approved candidate link advances this workflow. When you approve a Supplier Material against an Ingredient Specification, you establish that this vendor's product satisfies the R&D-governed standard — enabling downstream sourcing, compliance, and cost modeling that depends on that governance chain.

11. Future Governance Layers

Two governance layers are planned but not yet implemented. Understanding their intended role helps you appreciate why the current Ingredient Specification layer is designed as it is.

Supplier Specification (planned)

A Supplier Specification is the ingredient standard as claimed by the supplier — typically documented in their COA (Certificate of Analysis) or product specification sheet. It describes what the supplier says they are delivering, which may differ from the R&D-governed Ingredient Specification in specific limits, test methods, or attribute scope.

When implemented, the Supplier Specification layer will allow direct comparison:

Ingredient Spec requiresAshwagandha Root Extract ≥5% Withanolides (HPLC) · Heavy metals per USP 232

Supplier Spec claimsAshwagandha Root Extract 5.2% Withanolides (HPLC) · Pb <0.5 ppm · As <0.5 ppm

Comparison resultSupplier meets requirement ✓

Quality Verification (planned)

A Quality Verification is the actual lot-level test result for a received ingredient lot — comparing what the supplier delivered against both the Ingredient Specification and the Supplier Specification. This becomes the compliance record under 21 CFR Part 111.

Lot receivedLot 2024-0812-AS, received 2024-08-15

COA result5.1% Withanolides (HPLC) · Microbiological pass

Against specificationMeets ≥5% requirement ✓ · Meets microbiological limits ✓

Release decisionApproved for manufacturing

Current platform scope: Material Master currently implements Materials, Forms, Ingredient Specifications, and Supplier Materials. Supplier Specification and Quality Verification are future layers. No dates are committed. The architecture is designed to accommodate them when priorities support implementation.

12. Packaging vs Ingredients

Material Master handles three types of supplier materials differently:

Type	Examples	Status	What to do
Ingredient	Vitamins, minerals, botanicals, amino acids, enzymes, fibers, excipients	🟢 Fully operational	Use the Governance Queue (select Ingredient domain filter). Engine generates candidates.
Packaging Materials	Capsule shells, HDPE bottles, closures, droppers	🟡 Partially operational	Capsule shells and bottles have canonical entries. Closures need library expansion. Engine not yet run for packaging.
Packaging Artwork	Product labels, cartons, secondary packaging	⚪ Assessment mode	These are product artifacts — they do not map to a single canonical material. Use Assessment Mode to document status without forcing a canonical link.
Branded	KSM-66®, BioPerine®, Albion minerals, Cognizin®	🟡 Partially operational	Branded ingredients map to the same canonical spec as their underlying active. The brand name stays at the supplier material level — only the specification link is canonical.

Packaging artwork rule: Labels, cartons, and secondary packaging are product-level artifacts. They describe finished goods, not raw materials. Do not create canonical Materials for them. Use "Exclude SM" for items that will never have a canonical mapping.

13. Ingredient Specification Management

The Library is the primary ingredient governance workspace. Expanding any material row shows all forms with their Ingredient Specifications as interactive cards. You can Create, Open, Edit, Clone, and Retire Ingredient Specifications directly from the Library — without navigating to another workspace.

Status lifecycle

activePublished — governs stewardship matching. Can be edited, cloned, or retired.

draftCreated by Clone — not yet active. Edit to finalize, then activate via the Ingredient Spec Explorer.

retiringRetirement requested by a steward. Awaiting admin confirmation. Not yet retired.

retiredPermanently withdrawn. Historical record preserved. No new links possible.

Actions available from the Library

Action	When to use	Result
Open	Read the full specification detail including all identity, potency, botanical, and certification attributes	Read-only view modal. No changes made.
Edit	Update name, grade, potency, botanical markers, or certification flags on an active or draft specification	Fields updated; audit log entry written with actor email and changed fields.
Clone	Create a new specification based on an existing one — e.g., a different potency grade of the same form	New specification created in draft status with new spec code. Source unchanged.
Retire	Permanently withdraw a specification that is no longer the correct standard	Two-step: steward requests → admin confirms. Guard: blocked if any Supplier Material is linked.
+ Create Ingredient Spec	Form has no specifications at all (shows ⚠ None)	Opens guided creation wizard with Material and Form pre-selected.

Edit blocked on retired specs. Retired Ingredient Specifications are immutable — they cannot be edited or re-activated. Clone the retired spec to create an updated version.

Retire — two-step governance

Retiring an Ingredient Specification requires two separate actions:

Steward clicks Retire, enters a reason, and clicks Request Retirement. The specification status changes to retiring.
An admin must confirm the retirement separately. Only then does status change to retired.

Guard condition: If any Supplier Material is linked to the specification, the retire request is blocked. Remove all links before requesting retirement.

Step-by-step: Create from Library

Open Library. Select ⚠ Needs Ingredient Specs from the filter.
Expand a material row. Find a form showing ⚠ None.
Click + Create Ingredient Spec. The wizard opens with the form pre-selected.
Confirm the template, enter name and attributes, click Create Ingredient Specification.
The Library refreshes automatically showing the new spec.

Downstream impact of having specifications

Governance Queue: Candidates resolve at State A (spec-level) instead of State B/C/D — faster approval
Estimating: Formulas reference a specific grade rather than just a form
Compliance: 21 CFR Part 111 documentation can reference the governed standard
Future: Suppliers will declare compliance against this Ingredient Specification

14. Tab Reference

As of Release 62, the navigation reflects the steward workflow rather than the system architecture. There are now 5 tabs. The Ingredient Queue, Packaging Queue, and Branded Queue are now domain filters within Governance Queue — not separate top-level tabs.

Command Center Your starting point. Start Here panel, Today's Steward Focus, coverage health, next best actions, and operational KPIs. The intelligence engine runner is in the Administrative Actions section at the bottom.

Governance Queue Your primary stewardship workspace. Fast Lane for high-confidence matches. Confidence-tier queue tiles. Split-pane workbench. Domain filter for Ingredient / Packaging / Branded. Keyboard shortcuts (A/S/R/N). Previously labeled "Intelligence", then "Work Queue".

Library Browse the canonical material hierarchy. Search by name, synonym, or scientific name. Verify what exists before creating anything new.

Specifications Browse and create canonical specifications. Split-pane: spec list on left, detail on right. Guided creation modal with 9 template families.

Analytics Business-facing summary of platform impact: coverage gain, stewardship impact metrics, and opportunity concentration. For leadership and process owners. Previously labeled "Value".

Domain queues in Release 62: Ingredient Queue, Packaging Queue, and Branded Queue are now domain filters within the Governance Queue tab. Select "Ingredient", "Packaging", or "Branded" from the domain dropdown inside Governance Queue. All review functionality is preserved — only the navigation location changed.

15. What Not To Do

Violations create permanent incorrect data. These rules protect the integrity of every formulation and report that depends on Material Master.

Do not approve just to clear the queue. An incorrect approval creates a permanent link used in formulations and compliance reports. Skip if unsure. There is no undo for approved links.
Do not map a blend to a single-material canonical record. A six-enzyme blend is not "Protease." A multi-strain probiotic is not "Lactobacillus." Use Skip or Exclude for blends — never force a multi-component item into a single canonical mapping.
Do not treat the confidence score as the only thing that matters. A score of 85 is a strong signal, but you are still the steward. Read the "Why this was matched" evidence. Verify the canonical path makes sense for this specific supplier item.
Do not create duplicate canonical materials. Search the Library Explorer first. If a material already exists under a different name or synonym, add the new name as a synonym — do not create a second material.
Do not create specifications ahead of demand. Only create a specification when a real supplier material requires it. Pre-populating the library with untested specifications creates maintenance overhead and may introduce incorrect quality standards.
Do not approve a State C candidate without knowing which specification is correct. If two specifications exist for a form and you are unsure which applies to this supplier item — skip it. Investigate via Full Review or check with your procurement / QA team.

16. Recent Improvements

This section summarizes significant platform releases.

57B Core Dietary Supplement Library Expansion: 25 new canonical materials including Fibers/Prebiotics (Inulin, FOS, Psyllium, PHGG), Digestive Enzymes (Bromelain, Papain, Protease, Lipase, Lactase), Joint Health (MSM, Glucosamine, Chondroitin), Betaine, Monk Fruit, Sucralose, Lecithin, Rice Flour, Phosphatidylserine, NMN. Library now at 171 materials / 344 forms.

59 Specification Explorer: searchable, filterable spec list with structured detail view. Guided specification creation modal with 9 template families (Botanical, Mushroom, Mineral, Vitamin, Amino Acid, Enzyme, Fiber, Specialty, Excipient).

60 Navigation rationalization and 30 new canonical specifications (MAT-SPEC-0060 → MAT-SPEC-0089) covering botanicals, mushrooms, minerals, specialty compounds, and amino acids. Library now at 89 total specifications.

60A Steward Productivity: High Confidence Fast Lane hero, business-friendly queue labels (Ready / Needs Review / Needs Research), "Why this was matched" explainability section, session metrics strip, Approve & Next / Skip & Next labels, Stewardship Health Command Center section.

61 Guided Workflow & User Journey: Start Here panel on Command Center, Workflow Journey Map, Canonical Hierarchy Education, Today's Steward Focus, Coverage Improvement Story, purpose statements on every tab, queue status definitions in Intelligence tab, complete User Guide rewrite for business users (this guide).

62 Work Queue Consolidation & Workflow-First Navigation: Intelligence tab renamed to "Work Queue" and moved to position 2 (after Command Center). Ingredient Queue, Packaging Queue, and Branded Queue retired as top-level tabs — now domain filters within Work Queue. Value tab renamed "Analytics". Engine runner relocated from Work Queue to Command Center Administrative Actions section. "How Material Master Works" educational card collapsed by default. Migration notice in Work Queue for one release cycle. User Guide v3.2.

63 Ingredient Specification Nomenclature & Value Chain Education: "Specification" terminology updated to "Ingredient Specification" throughout business-facing UI. Definition card, value chain, 3-stage lifecycle grid. User Guide v3.3.

63B Governance Lifecycle & Full Workflow Education: Full 6-tier governance chain (Material → Form → Ingredient Specification → Supplier Specification [future] → Supplier Material → Quality Verification [future]) with ownership model. 5-stage business workflow (Estimating / R&D / Sourcing / Purchasing / Compliance). Work Queue approval value messaging. SM Coverage label clarification. User Guide v3.4.

64 Ingredient Specification Steward Workflow: Library becomes active governance workbench. Forms showing "Needs Specs" now include "⚠ None / + Create Ingredient Spec" actionable button — launches creation wizard with Material and Form pre-populated. Template auto-suggested from material class. After save, Library refreshes automatically. "⚠ Needs Ingredient Specs" Library filter shows all gaps. Library totals bar shows clickable missing-spec count. Empty state messaging explains governance impact. User Guide v3.5 Section 13: Creating Ingredient Specifications from the Library.

65D-A Navigation & Terminology Alignment: "Work Queue" renamed to "Governance Queue" throughout UI and User Guide. Ingredient Specs tab contextual help updated to "R&D Governed Enterprise Ingredient Requirements". Navigation order unchanged (Command Center | Governance Queue | Library | Ingredient Specs | Analytics). internal data-tab values unchanged — no API or routing impact. User Guide v3.8.

65C-B Ingredient Specification visibility fix: spec-explorer endpoint removed spec_status='active' filter — Explorer now shows all lifecycle states (active, draft, retiring, retired). Status badge added to Explorer spec cards. supply-chain wrangler.toml [[routes]] fix (65C-A): GitHub Actions was reporting "No targets deployed" — spec-clone, spec-edit, spec-retire endpoints not deployed to production without routes in wrangler.toml.

65C Ingredient Specification Management UX: Library becomes full ingredient governance workbench. Expanded spec cards in form rows show: spec code, status badge (active/draft/retiring/retired), created/modified dates, potency/grade/certification attributes. Action buttons: Open (read-only detail modal), Edit (pre-populated form → spec-edit endpoint), Clone (name input → spec-clone → new draft), Retire (governance warning + reason → spec-retire → sets retiring status, awaiting admin confirmation). Backend: spec-list endpoint updated to return spec_status, created_at, updated_at. New lib-spec-mgmt-modal at root level for Open/Edit/Retire views. User Guide v3.7 — Section 13 rewritten: full lifecycle table, action reference, retire two-step process, downstream impact.

65B Ingredient Specification Management Foundation: requireRole() authorization enforced at Worker layer on 10 write endpoints. New endpoints: spec-edit, spec-clone, spec-retire, spec-retire-confirm. Lifecycle states: draft/active/retiring/retired. Audit log (material_spec_audit_log, migration 0035). Retire requires dual confirmation and guard condition (no linked SMs).

63A Ingredient Governance Architecture Clarification (documentation only — no code changes): TARGET-ARCHITECTURE.md — Ingredient Governance Lifecycle Architecture section added with full 6-tier hierarchy, layer purposes table, formula relationship model, and matching engine architecture. CANONICAL-DATA-MODEL.md — Ingredient Governance Lifecycle section added with ownership model and formula relationship principle. MATERIAL-SPECIFICATION-STANDARD.md v1.2 — Formal Ingredient Specification definition, Formula Relationship Architecture, and Matching Engine Architecture added. ROADMAP-ODS.md — Phase 7A: Supplier Specification Layer and Quality Verification Layer roadmap items added with draft schema. User Guide v3.6 — Formula relationship section added (formulas consume Ingredient Specifications, not Supplier Materials).

17. FAQ

What is the difference between a Material, a Form, and a Specification?

Think of it this way: Magnesium is the Material (what it IS). Magnesium Glycinate Powder is the Form (how it is presented). Magnesium Glycinate 18% Elemental Mg is the Specification (the quality standard). Supplier materials link to Specifications — so two vendors selling Magnesium Glycinate at 18% elemental can both link to the same specification.

What does Approve actually do?

Approving creates a permanent record linking a specific supplier material (e.g., SOURCE-0042 from Vendor A) to a specific canonical specification (e.g., MAT-SPEC-0037 Magnesium Glycinate). This link:

Appears in formulation cost models
Enables procurement analytics (how many vendors supply this spec)
Supports 21 CFR Part 111 documentation chains
Is permanent — contact TWMD engineering for administrative corrections

What is the difference between "Reject & Next" and "Exclude SM"?

Reject & Next says the proposed match is wrong — but the supplier material itself may have other or future correct candidates. The SM stays in the queue.

Exclude SM says this supplier material should never be in the canonical mapping workflow at all — for example, it is water, packaging waste, a test sample, or an item with no appropriate canonical entry. The SM is removed from all active queues.

The score is only 42 (Needs Research) but the match looks correct. Should I approve?

Yes — you can approve a low-confidence candidate if the match evidence makes sense to you. The score is a guide, not a requirement. A low score typically means the engine only found weak signals (partial name match, form type keyword only). Before approving: verify in the Library that the Material → Form → Specification chain accurately represents this vendor item. If you are not 100% certain — skip it.

A form has no specifications (State D). What do I do?

In the workbench, click Full Review ↗. In the full workspace, clicking Approve will show a "+ Create Specification" button. Fill in the specification details (name, potency, grade, certifications). The new spec is immediately available for confirmation — you do not need to leave the workflow. Alternatively, create the spec in the Specification Explorer tab first, then return to the queue.

How do I know when to re-run the intelligence engine?

Re-run after: new library seeds are applied (new materials, forms, or synonyms added), after new specifications are created during curation, or after a library governance correction. The engine is always safe to re-run — it replaces suggested candidates but never changes approved or rejected records. Go to: Intelligence tab → Run Engine… → Ingredient → Dry Run → Execute.

I approved the wrong candidate. What now?

Approved links are intentionally permanent (governance rule ADR-MAT-002). If you discover an incorrect approval, contact the TWMD engineering team. An administrative correction can be made in the database with a corresponding audit entry. This is a rare, escalated path — not a self-service action. The best prevention is to use Skip & Next whenever you are not fully confident.

Why are some items unmatched even after running the engine?

Unmatched items typically fall into one of these categories:

Library gap: The canonical library does not yet contain this ingredient category. Check the Library Gap Explorer on the Command Center.
Complex blend: The item is a multi-component blend (enzyme blend, probiotic blend, flavor system) that cannot be cleanly matched to a single canonical material.
Engine not re-run: The engine was last run before a library expansion that would have matched this item. Re-run the engine for the ingredient domain.
Naming patterns: The supplier item name uses non-standard terminology not yet in the synonyms library.

Are my session progress counters saved anywhere?

No. The session counters (approved / rejected / skipped this session) are browser-only. They reset when the page reloads. All actual decisions — approvals, rejections, and exclusions — are permanently stored in the audit log with your email and timestamp.

The Command Center is the first tab in Material Master. It provides an operational overview of platform health, prioritized actions, and coverage progress — intended to be the steward's starting point before each session.

Section 1 — Executive Summary

Four metrics visible immediately at the top: Total Supplier Materials, Linked (linked to a specification), Suggested (intelligence engine has a candidate), and Unmatched (no candidates generated). The large percentage shows overall coverage. Click any tile to navigate directly to that queue.

Section 2 — Coverage Health

Proportional bars showing the breakdown of ingredient and packaging supplier materials:

Section 3 — Next Best Actions

Section 4 — Opportunity Center

A ranked table showing which canonical materials have the most supplier materials waiting for approval. Prioritize these materials. Approving a material that appears in 25 supplier records links 25 SMs in the same session — far higher value than approving 25 individual one-off items.

Section 5 — Library Gap Explorer

Section 6 — Material Readiness

Section 7 — Specification Coverage

Shows what percentage of active material forms have at least one canonical specification. A progress bar and counts show covered vs uncovered forms. Forms without specifications will result in State D during approval. A link to the Specification Explorer is provided.

Section 8 — Stewardship Health

A live snapshot of the intelligence candidate pipeline, organized by business-friendly status labels:

The Coverage Maturity Funnel below the KPIs shows the pipeline as three stages: Linked → Has Candidates → Unmatched.

Section 9 — Backlog Detail

Clickable tiles for each intelligence confidence tier. Click a tile to jump directly to that queue on the Intelligence tab. Uses the same business-friendly labels as Stewardship Health.

4. Value Realization Center

The Value Realization Center is a business-facing tab that translates Material Master stewardship activity into measurable operational progress. It is intended for leadership and process owners who want to understand platform impact without navigating stewardship queues.

Purpose

The Command Center answers what is happening operationally. The Value Realization Center answers what value has been created and what remains.

Sections

Executive Narrative

A factual summary paragraph computed from live counts: how many supplier materials are linked, what the canonical library contains, and how many candidates are awaiting review. Updated on each Refresh.

Coverage Value Summary

Four KPI tiles: Coverage %, Linked, Candidates, and Unmatched supplier materials. A proportional progress bar shows the distribution across all supplier materials.

Stewardship Impact

Six metrics showing work completed: Approved Links, Canonical Materials, Specifications, Rejected Candidates, Material Forms, and Synonyms.

Opportunity Concentration

A ranked table of canonical materials ordered by the number of supplier materials confirmed linked to them. Materials at the top have the most coverage established; continued stewardship on materials with high candidate counts creates the most value per approval session.

Library Gap Value

Categorizes unmatched ingredient supplier materials by type: Botanical Extracts, Flavor Systems, Organic/Superfood, Branded/Proprietary, Oils & Liquids, Probiotics, and Other. Each category includes a note on addressability:

Domain Readiness Summary

Canonical Library — Current State

Current library counts: materials, forms, specifications, and synonyms. Historical comparison is not displayed because prior snapshots are not persisted. A "Browse Library →" button navigates to the Material Explorer for detailed inspection.

5. Intelligence Queues

The Intelligence tab shows all supplier materials that have been evaluated by the matching engine, segmented by confidence level and resolution status. The stat tiles at the top are clickable — clicking a tile loads that queue in the list below.

High Confidence Fast Lane

When at least one "Ready For Approval" candidate exists, a Fast Lane hero appears at the top of the Intelligence tab. Clicking it opens the Ready For Approval queue directly. For experienced stewards, the Fast Lane allows processing 10–60 high-confidence approvals in under 15 minutes using keyboard shortcuts (A / S / N).

Confidence tiers — business-friendly labels

Confidence is a score (0–100) combining all match signals. Higher score means stronger evidence. Use confidence as a guide, not an automatic approval trigger.

Resolution status tiles

Quick Approve

For HIGH confidence candidates that are matched at the Specification level (State A), a ✓ Approve button appears directly in the queue row. The full match path (Material › Form › Specification) is visible before clicking. Clicking approves and links the SM without opening the full workspace.

Filter controls

6. Fast Review / Workbench Mode

Workbench Mode keeps the queue list visible on the left while showing a detail panel on the right. Clicking a queue row populates the right panel — no full-page overlay, no context loss. After approve/reject/skip, the steward auto-advances to the next item.

Why this was matched — Candidate Explainability

Every candidate in the workbench shows a "Why this was matched" section listing the specific signals the intelligence engine fired, with point values. This lets you understand and verify the recommendation before approving. Common signals:

The total score is the sum of fired signal points, capped at 100. Scores ≥ 75 enter the "Ready For Approval" lane.

Approval flow in the workbench

Keyboard shortcuts

Session progress

State	Condition	Workbench action
State A	Specification-level match — spec already identified	Click Approve & Next → direct submit → auto-advances to next item
State B	Form-level match — exactly one specification exists	Click Approve & Next → auto-select the single spec → Confirm Approval
State C	Form-level match — multiple specifications exist	Click Approve & Next → dropdown appears → select the correct spec → Confirm Approval
State D	Form-level match — no specifications exist for this form	Click Full Review ↗ → use inline specification creation in the full workspace

Above the queue list: position N of M · approved · rejected · skipped. This is browser-session state only — it resets when the page reloads. No database writes.

Full Review

Click Full Review ↗ on any workbench item to open the full workspace overlay. The full workspace shows all candidates (not just the top-ranked one), the complete audit history, the inline specification creator for State D, and the Exclude SM action. Use Full Review for complex cases, blends, or items requiring investigation.

6. Material Explorer

The Library tab shows the full canonical material hierarchy. Use it to browse, search, and verify what is in the library before approving candidates.

Browsing materials

Click Refresh to load the library. Materials are grouped by class with readiness badges:

Material relationship visualization

Expanding a material row shows a compact hierarchy chain at the top of the detail view:

Each node shows the count and is color-coded: green = all populated, amber = some missing. Below the chain: synonyms, then a forms table showing each form with its spec count and linked SM count.

Expanding form specifications

In the forms table, click the spec count cell (e.g., "3 specs ▸") to expand and see all specification names for that form inline. This is useful to verify whether the right specification already exists before deciding how to handle a candidate in the queue.

Searching

The search box performs synonym-aware search: typing "KSM-66" will find the Ashwagandha material because "KSM-66" is registered as a trade name synonym. Scientific names and common aliases both work.

7. Steward Decision Rules

Every decision you make in the workbench or queue creates an audited, permanent record. The four actions below are mutually exclusive for any given candidate.

What "Reject Candidate" means

Action	When to use	What it does
Approve & Link	The proposed Material › Form › Specification accurately represents this supplier material. Evidence is strong. You are confident in the match.	Creates a permanent link: `supplier_materials.material_specification_id` is set. This link is used in formulations, procurement, and compliance. Irreversible by design.
Create Specification	The Material and Form are correct, but the specification with the right potency / grade / extraction method does not exist yet. Example: Magnesium Glycinate is a form, but the exact grade (e.g., "Magnesium Glycinate 20% Mg") has no specification record.	Use State D inline creation in Full Review, or create the spec in the Library Explorer first, then re-run the intelligence engine to generate updated candidates.
Skip for Later	The record is ambiguous. You need more information. The candidate looks partially right but you are not certain. The item is a complex blend. You want to return to this item after checking other sources.	Increments the session skip counter. The SM stays in the queue at the same position. No database record created.
Exclude SM	This supplier material should not be linked to the canonical hierarchy at all. Examples: water, packaging waste, test samples, items that are not discrete purchasable materials, items with no appropriate canonical mapping.	Sets `curation_status = 'excluded'` on the supplier material. Writes to audit log. SM will no longer appear in active queues. Requires a stated reason.

Reject is a candidate-level action, not an SM-level action. Rejecting a candidate means "this proposed match is wrong" — not "this SM should be excluded." If an SM has multiple candidates, rejecting one leaves the others available. The SM stays in the queue and can receive future candidates from the next engine run.

8. Complex Materials and Blends

Some supplier materials do not map cleanly to a single canonical Material/Form/Specification. Understanding these cases prevents incorrect approvals.

Types of complex materials

How to handle them

Pattern detection in the workbench

The workbench automatically detects likely complex materials using name patterns (blend, proprietary, enzyme activity units like GDU/g, HUT/g, multiple comma-separated actives) and shows a caution banner. This is an approximation — use your judgment alongside the banner.

9. Coverage Interpretation

What the three states mean

Unmatched does not mean invalid

An unmatched supplier material is not a data quality problem in the SM itself. It usually indicates a library gap — the canonical material entry does not exist yet. The Library Gap Explorer on the Command Center shows what categories are driving the unmatched pool.

When to re-run the engine

The engine is accessible from the Intelligence tab: click Run Engine…, select Ingredient domain, run Dry Run first, then Execute.

10. What Not To Do

11. Recent Improvements

This section summarizes platform improvements since the original User Guide v1.0.

13. Specification Attributes

Specification Attributes define the testable requirements that a specification must meet. They are linked to individual specifications and carry limit types, measurement units, and method references. Attributes are governed by the Specification Attribute Types catalog (24 types across 6 categories).

Attribute categories

13. Governance

Audit logging

Every stewardship decision is written to material_curation_log with: action, decision_type, curator_email, decided_at, and notes. The full audit history for any supplier material is visible in the Full Review workspace under Audit History.

Immutability rules

Tenant isolation

All Material Master records carry tenant_id = 'snl'. All API queries enforce tenant scoping. Cross-tenant data access is not possible through this interface.

Creating canonical records

New materials, forms, and specifications can only be created through the Material Master workspace. Each creation is validated for duplicate prevention. The system will warn you if a material with the same name already exists.