cbrowser 16.15.2 → 16.15.4

package/README.md

@@ -106,13 +106,17 @@ CBrowser models 25 research-backed cognitive traits to simulate how real users t
 |-------|---------------|----------------|
 | **Patience** | — | How quickly users abandon on friction |
 | **Frustration** | — | Accumulates with errors, decays with success |
-| **Decision Fatigue** | Baumeister's ego depletion | Users start choosing defaults after too many decisions |
-| **Dual-Process Thinking** | Kahneman (Nobel Prize) | System 1 (fast/automatic) vs System 2 (slow/deliberate) |
+| **Decision Fatigue** | Baumeister et al. (1998)* | Users start choosing defaults after too many decisions |
+| **Dual-Process Thinking** | Kahneman (2011) | System 1 (fast/automatic) vs System 2 (slow/deliberate) |
 | **Self-Efficacy** | Bandura (1977) | Belief in ability to solve problems; low = faster abandonment |
 | **Satisficing** | Simon (1956) | Accept "good enough" vs. optimize; satisficers decide 50% faster |
 | **Trust Calibration** | Fogg (2003) | Baseline trust affects click-through by 40% |
 | **Interrupt Recovery** | Mark et al. (2005) | Average recovery time 23min; models context preservation |
 
+*\*Note: Ego depletion research has faced [replication challenges](https://doi.org/10.1177/1745691616652873). CBrowser uses a simplified decision fatigue model focused on observable choice patterns.*
+
+**Full documentation:** [Research Methodology](https://github.com/alexandriashai/cbrowser/wiki/Research-Methodology) · [Trait Index](https://github.com/alexandriashai/cbrowser/wiki/Trait-Index) · [Bibliography](https://github.com/alexandriashai/cbrowser/wiki/Bibliography)
+
 ### Abandonment Detection
 
 The simulation stops when a realistic user would give up:
@@ -454,3 +458,9 @@ For commercial licensing: [alexandria.shai.eden@gmail.com](mailto:alexandria.sha
 - [A+ Assessment Report](https://claude.ai/public/artifacts/0cee560d-60b8-44d6-8eec-e674fbfac9c4)
 - [Remote MCP Server Guide](docs/REMOTE-MCP-SERVER.md)
 - [Roadmap](ROADMAP.md)
+
+### Research Documentation
+
+- [Research Methodology](https://github.com/alexandriashai/cbrowser/wiki/Research-Methodology) — How 25 traits were selected and validated
+- [Trait Index](https://github.com/alexandriashai/cbrowser/wiki/Trait-Index) — All cognitive traits with citations
+- [Bibliography](https://github.com/alexandriashai/cbrowser/wiki/Bibliography) — Complete academic references

package/docs/research/Research-Methodology.md

@@ -149,6 +149,30 @@ Accessibility personas include trait modifications based on disability research:
 
 ---
 
+## Validation Status
+
+> **Important:** CBrowser's trait implementations are **research-informed heuristics**, not direct measurements. The correlation values and behavioral parameters presented throughout this documentation are **educated estimates** derived from related HCI and cognitive psychology literature, not empirical calibrations from CBrowser-specific validation studies.
+>
+> Empirical calibration is planned — see [GitHub Issue #95](https://github.com/alexandriashai/cbrowser/issues/95) for methodology and timeline.
+
+### Current State
+
+| Aspect | Status |
+|--------|--------|
+| Trait definitions | Based on peer-reviewed research |
+| Behavioral parameters | Theoretically derived from related literature |
+| Persona profiles | Research-informed archetypes |
+| Correlation values | Educated estimates, not direct measurements |
+
+### Planned Validation (GitHub #95)
+
+The empirical calibration planned for future versions will include:
+- A/B testing simulated vs. real user behavior
+- Statistical comparison against published benchmarks (Baymard, Nielsen Norman, etc.)
+- Iterative tuning until simulation distributions match empirical baselines
+
+---
+
 ## Validation Methods
 
 ### 1. Expert Review
@@ -158,17 +182,7 @@ Trait definitions and values reviewed by:
 - Cognitive psychologists
 - Accessibility specialists
 
-### 2. Behavioral Testing
-
-Cognitive journeys validated against real user testing data:
-
-| Metric | Correlation with Real Users |
-|--------|----------------------------|
-| Abandonment prediction | r = 0.72 |
-| Navigation patterns | r = 0.68 |
-| Error recovery | r = 0.65 |
-
-### 3. Comparative Analysis
+### 2. Comparative Analysis
 
 CBrowser personas compared against:
 - Nielsen Norman Group persona archetypes

package/docs/traits/Trait-AnchoringBias.md

@@ -112,7 +112,9 @@ The landmark demonstration of anchoring:
 - Countdown timers affect urgency perception
 - "X people are viewing this" shapes demand perception
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |--------------|-------------|-----------|

package/docs/traits/Trait-AttributionStyle.md

@@ -137,7 +137,9 @@ The three dimensions create distinct patterns:
 | **Growth** | Internal | Unstable | Controllable | "I wasn't focused. I'll try again carefully." High persistence. |
 | **Fixed Mindset** | Internal | Stable | Uncontrollable | "I'm just not good with technology." Low self-efficacy. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |--------------|-------------|-----------|

package/docs/traits/Trait-AuthoritySensitivity.md

@@ -70,7 +70,9 @@ Cialdini, R. B. (2001). *Influence: Science and practice* (4th ed.). Allyn and B
 - **Purchase Decisions**: Cross-references claims on independent review sites
 - **Information Architecture**: Prefers unfiltered, chronological content over curated selections
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Correlated Trait | Correlation | Mechanism |
 |------------------|-------------|-----------|

package/docs/traits/Trait-ChangeBlindness.md

@@ -80,7 +80,9 @@ Rensink, R. A., O'Regan, J. K., & Clark, J. J. (1997). To see or not to see: The
 - Price changes during session go undetected
 - Stock status changes ("In Stock" to "Out of Stock") are missed
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-Comprehension.md

@@ -67,7 +67,9 @@ Card, Moran, and Newell's GOMS model breaks user behavior into:
 | Moderate | Standard methods, typical operator times, basic selection |
 | High | Rich method library, efficient operators, optimal selection |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-Curiosity.md

@@ -69,7 +69,9 @@ Loewenstein (1994) extended Berlyne's work:
 | 0.6-0.8 | Curious | Actively explores beyond task requirements. Reads related articles and linked content. Investigates new features and options. Clicks on "learn more" links. Explores settings and customization. Time on site 30-40% above average. |
 | 0.8-1.0 | Highly Exploratory | Deep exploration of all available content. Reads documentation and help pages. Investigates every feature, setting, and option. Follows rabbit holes of linked content. May forget original task while exploring. Discovers hidden features. Time on site 50%+ above average. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-EmotionalContagion.md

@@ -72,7 +72,9 @@ Kramer, A. D. I., Guillory, J. E., & Hancock, J. T. (2014). Experimental evidenc
 - **Content Engagement**: Shares based on utility, not emotional resonance
 - **Customer Support**: Evaluates resolution quality, not emotional tone
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Correlated Trait | Correlation | Mechanism |
 |------------------|-------------|-----------|

package/docs/traits/Trait-FOMO.md

@@ -75,7 +75,9 @@ Cialdini, R. B. (2001). *Influence: Science and practice* (4th ed.). Allyn and B
 - **Cart Abandonment**: Unaffected by urgency emails; returns when ready or not at all
 - **Social Media**: Uses purposefully; comfortable missing content
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Correlated Trait | Correlation | Mechanism |
 |------------------|-------------|-----------|

package/docs/traits/Trait-Index.md

@@ -100,7 +100,9 @@ How social context and comparison affect user behavior.
 
 ---
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 Traits don't exist in isolation. Research-backed correlations:
 

package/docs/traits/Trait-InformationForaging.md

@@ -109,7 +109,9 @@ The "patch" in foraging theory is analogous to a web page or site section:
 | Preview/Tooltip | Hover information | Low-Medium |
 | Domain/URL | Site credibility signals | Low |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |--------------|-------------|-----------|

package/docs/traits/Trait-InterruptRecovery.md

@@ -152,7 +152,9 @@ function getResumptionBehavior(
 }
 ```
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 Research and theoretical models indicate the following correlations:
 

package/docs/traits/Trait-MentalModelRigidity.md

@@ -91,7 +91,9 @@ Carroll, J. M., & Rosson, M. B. (1987). Paradox of the active user. In J. M. Car
 - Looks for social login options in different position
 - Assumes password visible toggle is checkbox when it's icon
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-MetacognitivePlanning.md

@@ -80,7 +80,9 @@ Dunlosky, J., & Metcalfe, J. (2009). *Metacognition*. SAGE Publications.
 | High | Diagnoses error cause; tries multiple systematic solutions |
 | Very High | Prevents errors through preview; when errors occur, uses systematic debugging |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Research Basis |
 |---------------|-------------|----------------|

package/docs/traits/Trait-Patience.md

@@ -49,7 +49,9 @@ Nielsen, J. (1993). *Usability Engineering*. Academic Press. ISBN 978-0125184069
 | 0.6-0.8 | Patient | Tolerates 15-20 seconds for complex operations. Reads loading messages and status updates. Willing to wait for quality content. Doesn't reflexively click repeatedly. Understands that complex operations take time. Rarely abandons due to speed alone. |
 | 0.8-1.0 | Very Patient | Tolerates 30+ seconds for important tasks. Reads terms and conditions fully. Waits for complete page loads before interacting. Never double-clicks out of impatience. Willing to retry failed operations. Provides patience buffer for first-time site visits. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-Persistence.md

@@ -59,7 +59,9 @@ Duckworth's Grit Scale measures two factors relevant to web behavior:
 - Finishing what is started
 - **Web impact**: Retries failed actions, seeks help, tries alternative approaches
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-ProceduralFluency.md

@@ -91,7 +91,9 @@ Sweller, J., & Cooper, G. A. (1985). The use of worked examples as a substitute
 | High | Minimal observable load; confident movements; quick decisions |
 | Very High | No observable load; parallel processing; possibly bored with simple interfaces |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Research Basis |
 |---------------|-------------|----------------|

package/docs/traits/Trait-ReadingTendency.md

@@ -70,7 +70,9 @@ Nielsen's eyetracking research identified the F-shaped reading pattern:
 | 0.6-0.8 | Thorough Reader | Reads most of headlines, subheads, and significant portions of body text. Notices text warnings and important messages. Reads 40-60% of text. Follows links within content. Reads captions and labels. More likely to notice inline guidance. |
 | 0.8-1.0 | Complete Reader | Reads nearly all text content systematically. Reads terms and conditions. Notices footnotes and fine print. Reads 70%+ of text. Processes instructions before acting. Unlikely to miss text-based warnings. May read comments and supplementary content. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-Resilience.md

@@ -83,7 +83,9 @@ const errorTolerance = Math.floor(2 + (resilience * 10));
 // High resilience: 10-12 errors
 ```
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 Research and theoretical models indicate the following correlations:
 

package/docs/traits/Trait-RiskTolerance.md

@@ -48,7 +48,9 @@ Tversky, A., & Kahneman, D. (1992). Advances in prospect theory: Cumulative repr
 | 0.6-0.8 | Risk-Tolerant | Readily explores new websites. Enters email freely for content access. Tries new payment methods. Downloads apps without extensive research. Clicks on interesting links even from unfamiliar sources. Creates accounts easily. Minimal verification before form submission. |
 | 0.8-1.0 | Very Risk-Seeking | Clicks first, thinks later. Ignores security warnings. Enters personal data casually. Experiments with unverified sites and downloads. May fall for phishing without pattern recognition. No hesitation on unfamiliar checkouts. Dismisses browser warnings. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/docs/traits/Trait-Satisficing.md

@@ -98,7 +98,9 @@ Schwartz, B., Ward, A., Monterosso, J., Lyubomirsky, S., White, K., & Lehman, D.
 - Round numbers ("about 30" not "32")
 - Quick completion even if imprecise
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |--------------|-------------|-----------|

package/docs/traits/Trait-SelfEfficacy.md

@@ -102,7 +102,9 @@ function updateEfficacy(state: SelfEfficacyState, success: boolean): void {
 }
 ```
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 Research and theoretical models indicate the following correlations:
 

package/docs/traits/Trait-SocialProofSensitivity.md

@@ -75,7 +75,9 @@ Cialdini, R. B. (2001). *Influence: Science and practice* (4th ed.). Allyn and B
 - **Review Sorting**: May read negative reviews specifically to find edge cases
 - **Recommendations**: Explores independently rather than following suggestions
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Correlated Trait | Correlation | Mechanism |
 |------------------|-------------|-----------|

package/docs/traits/Trait-TimeHorizon.md

@@ -127,7 +127,9 @@ Frederick, S., Loewenstein, G., & O'Donoghue, T. (2002). Time discounting and ti
 - Newsletter subscriptions
 - Documentation and reference material
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |--------------|-------------|-----------|

package/docs/traits/Trait-TransferLearning.md

@@ -103,7 +103,9 @@ Based on Barnett & Ceci (2002), transfer distance affects success rate:
 | Very Far | Different domain, abstract similarity | 10-30% | Web form skills to mobile app form |
 | Analogical | Structural similarity only | 10-20% | Folder organization to database organization |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Research Basis |
 |---------------|-------------|----------------|

package/docs/traits/Trait-TrustCalibration.md

@@ -132,7 +132,9 @@ function handleTrustBetrayal(state: TrustState, severity: number): void {
 }
 ```
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 Research and theoretical models indicate the following correlations:
 

package/docs/traits/Trait-WorkingMemory.md

@@ -66,7 +66,9 @@ Miller discovered that while raw information capacity is limited, we can increas
 | 0.6-0.8 | High | Handles 8-10 chunks comfortably. Manages complex dashboards. Tracks multiple open tasks. Compares 5+ options mentally. Remembers earlier form inputs while completing later sections. Navigates complex hierarchies. |
 | 0.8-1.0 | Very High | Handles 10+ chunks. Power-user of complex interfaces. Tracks multiple simultaneous processes. Mentally holds entire site structure. Rarely needs visual aids for memory. Can complete complex forms from memory. |
 
-## Trait Correlations
+## Estimated Trait Correlations
+
+> *Correlation estimates are derived from related research findings and theoretical models. Empirical calibration is planned ([GitHub #95](https://github.com/alexandriashai/cbrowser/issues/95)).*
 
 | Related Trait | Correlation | Mechanism |
 |---------------|-------------|-----------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "16.15.2",
+  "version": "16.15.4",
   "type": "module",
   "description": "Cognitive browser automation that thinks like your users—and helps AI agents navigate too. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery. Sites that pass CBrowser's cognitive tests are easier for both humans and AI agents to navigate.",
   "main": "dist/index.js",