docs: improve documentation UX and best practices#455
Closed
docs: improve documentation UX and best practices#455
Conversation
- Extended getPercentiles() to return all quartiles (min, p25, p50, p75, p90, p95, p99, max) - Added showPercentileBands() call to main report function - Fixed compilation error where p.p25, p.p75, p.min, p.max were undefined - Percentile bands now show distribution across 5 bands with color-coded emojis - Well-distributed samples show balanced performance analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fixed assemble command to skip subcommand (args[1..]) - Removed incorrect 12-byte header assumption in disassembler - Fixed decoder: 16-bit immediate at bits [31:17] - Fixed encoder: LDI/STI/STORE/LOAD_MEM/JZ/JNZ shift 16→17 - Fixed encoder: 3-operand src1/src2 shifts 11→13, 14→18 - Fixed encoder: SHL/SHR shift_amt shift 11→13 All 9 instructions now assemble/disassemble/run correctly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fixed assemble command to skip subcommand (args[1..]) - Removed incorrect 12-byte header assumption in disassembler - Fixed decoder: 16-bit immediate at bits [31:17] - Fixed encoder: LDI/STI/STORE/LOAD_MEM/JZ/JNZ shift 16→17 - Fixed encoder: 3-operand src1/src2 shifts 11→13, 14→18 - Fixed encoder: SHL/SHR shift_amt shift 11→13 All 9 instructions now assemble/disassemble/run correctly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added autocorrelation-based periodicity analysis - Detects periodic patterns in RTT data (CPU scheduling, GC, network waves) - Calculates autocorrelation for lags 1 to min(50, n/2) - Reports dominant period, periodicity score, and classification - Provides interpretation hints based on period duration - Classifies: Random, Weak, Moderate, Strong, Very Strong periodicity - Identifies possible causes: scheduler tick, GC, congestion, etc. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added autocorrelation-based periodicity analysis - Detects periodic patterns in RTT data (CPU scheduling, GC, network waves) - Calculates autocorrelation for lags 1 to min(50, n/2) - Reports dominant period, periodicity score, and classification - Provides interpretation hints based on period duration - Classifies: Random, Weak, Moderate, Strong, Very Strong periodicity - Identifies possible causes: scheduler tick, GC, congestion, etc. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added histogram-based mode detection for RTT distribution - Detects up to 5 distinct peaks/modes in RTT data - Identifies bimodal, trimodal, and multimodal patterns - Provides interpretation based on peak separation ratios - Possible causes: cache hit/miss, network paths, WiFi/Ethernet - Classifies: Uniform, Unimodal, Bimodal, Trimodal, Multimodal - Shows peak locations with sample percentages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added histogram-based mode detection for RTT distribution - Detects up to 5 distinct peaks/modes in RTT data - Identifies bimodal, trimodal, and multimodal patterns - Provides interpretation based on peak separation ratios - Possible causes: cache hit/miss, network paths, WiFi/Ethernet - Classifies: Uniform, Unimodal, Bimodal, Trimodal, Multimodal - Shows peak locations with sample percentages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added intelligent configuration recommendations based on statistics - Analyzes coefficient of variation for batch size suggestions - Recommends delay adjustments based on mean RTT - Suggests spike threshold tuning based on p99/p50 ratio - Calculates optimal timeout (2x max RTT) - Provides anomaly-based recommendations - Quality score assessment with action items - Trend-based performance degrading warnings - Sample count confidence recommendations - Configuration summary with key metrics Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added intelligent configuration recommendations based on statistics - Analyzes coefficient of variation for batch size suggestions - Recommends delay adjustments based on mean RTT - Suggests spike threshold tuning based on p99/p50 ratio - Calculates optimal timeout (2x max RTT) - Provides anomaly-based recommendations - Quality score assessment with action items - Trend-based performance degrading warnings - Sample count confidence recommendations - Configuration summary with key metrics Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added one-line health status summary - Shows status (EXCELLENT/GOOD/FAIR/POOR/CRITICAL) - Performance classification (Stable/Low/Moderate/High Variability) - Anomaly status (No/Few/Some/Many anomalies) - Quality score display with grade - Mean RTT range calculation - Jitter coefficient of variation display Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added one-line health status summary - Shows status (EXCELLENT/GOOD/FAIR/POOR/CRITICAL) - Performance classification (Stable/Low/Moderate/High Variability) - Anomaly status (No/Few/Some/Many anomalies) - Quality score display with grade - Mean RTT range calculation - Jitter coefficient of variation display Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Committed TRI-27 encoder i16 bitwise ops fix - Updated loop_state.md with v3.85 commit - UART echo test verified working (Quick Health Check) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Committed TRI-27 encoder i16 bitwise ops fix - Updated loop_state.md with v3.85 commit - UART echo test verified working (Quick Health Check) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added PerformanceProfile struct with predefined profiles - classifyPerformanceProfile() - auto-detects connection type - Profiles: Real-time, Interactive, Fast Local, Standard, Moderate, High Latency, Variable - showPerformanceProfile() - displays profile info with application recommendations - Includes suitable applications for each profile type - Based on mean RTT, P99, and coefficient of variation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added PerformanceProfile struct with predefined profiles - classifyPerformanceProfile() - auto-detects connection type - Profiles: Real-time, Interactive, Fast Local, Standard, Moderate, High Latency, Variable - showPerformanceProfile() - displays profile info with application recommendations - Includes suitable applications for each profile type - Based on mean RTT, P99, and coefficient of variation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Updated all version banners from v3.62/v3.80 to v3.86 - printUsage() now shows v3.86 - SIMULATION MODE banner now shows v3.86 - SIMULATION BATCH MODE banner now shows v3.86 - SIMULATION BATCH RESULTS banner now shows v3.86 - PERFORMANCE REPORT banner now shows v3.86 - All version strings are now consistent across the codebase Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Updated all version banners from v3.62/v3.80 to v3.86 - printUsage() now shows v3.86 - SIMULATION MODE banner now shows v3.86 - SIMULATION BATCH MODE banner now shows v3.86 - SIMULATION BATCH RESULTS banner now shows v3.86 - PERFORMANCE REPORT banner now shows v3.86 - All version strings are now consistent across the codebase Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added analyzeBursts() function using Median Absolute Deviation (MAD) - Detects consecutive high-latency samples (bursts) - Classifies burst severity: NONE/LOW/MODERATE/HIGH/SEVERE - Reports: burst count, affected samples, longest burst, avg burst length - Provides interpretation based on burst ratio - Integrated into statistical report output Features: - MAD-based threshold detection (threshold_multiplier parameter) - Consecutive sample tracking for burst identification - Percentage-based severity classification - Actionable interpretation for each severity level Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added analyzeBursts() function using Median Absolute Deviation (MAD) - Detects consecutive high-latency samples (bursts) - Classifies burst severity: NONE/LOW/MODERATE/HIGH/SEVERE - Reports: burst count, affected samples, longest burst, avg burst length - Provides interpretation based on burst ratio - Integrated into statistical report output Features: - MAD-based threshold detection (threshold_multiplier parameter) - Consecutive sample tracking for burst identification - Percentage-based severity classification - Actionable interpretation for each severity level Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added calculateStabilityScore() for comprehensive stability assessment - Four component scores: - Jitter Stability (based on coefficient of variation) - Consistency Score (based on IQR spread) - Burst Penalty (inverse of burst severity) - Trend Score (based on degradation detection) - Overall score: weighted average (35%/25%/25%/15%) - Grade assignment: A/B/C/D/F (90+/80+/70+/60+) - Actionable recommendations for each grade level - Color-coded output with emoji indicators Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added calculateStabilityScore() for comprehensive stability assessment - Four component scores: - Jitter Stability (based on coefficient of variation) - Consistency Score (based on IQR spread) - Burst Penalty (inverse of burst severity) - Trend Score (based on degradation detection) - Overall score: weighted average (35%/25%/25%/15%) - Grade assignment: A/B/C/D/F (90+/80+/70+/60+) - Actionable recommendations for each grade level - Color-coded output with emoji indicators Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added generateAdaptiveConfig() for optimal parameter calculation - Automatically calculates: - Baud rate (based on p99 latency) - Timeout (3x p99 + margin, min 500ms) - Delay (1.5x mean RTT, min 50ms) - Batch size (stability-based: 8/16/32) - Spike threshold (CV-based: 2.0/3.0/4.0) - Adaptive timeout flag (enabled for CV > 0.3) - RTS/CTS flag (enabled for batch >= 16) - Shows example command with all recommended parameters - Provides reasoning for configuration choices Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added generateAdaptiveConfig() for optimal parameter calculation - Automatically calculates: - Baud rate (based on p99 latency) - Timeout (3x p99 + margin, min 500ms) - Delay (1.5x mean RTT, min 50ms) - Batch size (stability-based: 8/16/32) - Spike threshold (CV-based: 2.0/3.0/4.0) - Adaptive timeout flag (enabled for CV > 0.3) - RTS/CTS flag (enabled for batch >= 16) - Shows example command with all recommended parameters - Provides reasoning for configuration choices Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added detectLossPattern() for failure pattern analysis - Pattern types: BURST, GROUPED, SCATTERED, ISOLATED, NO_LOSS - Severity classification: NONE/LOW/MODERATE/HIGH/SEVERE - Metrics: - Max consecutive failures - Scattered loss count - Periodicity score (0-100) - Pattern-based recommendations: - BURST: buffer overflow warnings, reduce batch size - GROUPED: loose connections, check cable, try different baud - SCATTERED: noise indicators, error correction suggestions - ISOLATED: stable connection, no action needed - Only displayed when packet loss is detected Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added detectLossPattern() for failure pattern analysis - Pattern types: BURST, GROUPED, SCATTERED, ISOLATED, NO_LOSS - Severity classification: NONE/LOW/MODERATE/HIGH/SEVERE - Metrics: - Max consecutive failures - Scattered loss count - Periodicity score (0-100) - Pattern-based recommendations: - BURST: buffer overflow warnings, reduce batch size - GROUPED: loose connections, check cable, try different baud - SCATTERED: noise indicators, error correction suggestions - ISOLATED: stable connection, no action needed - Only displayed when packet loss is detected Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added showSessionSummary() for comprehensive test report - Test Results: passed/total ratio, samples analyzed, failure info - Latency Summary: mean, jitter, min/max, p50/p99 - Quality Assessment: - Stability score with emoji indicators - Burst severity with burst count - Loss pattern with severity - Actionable recommendations: - Excellent (85+): suitable for real-time, no action needed - Good (70-84): consider adaptive timeout, monitor degradation - Fair (50-69): try different baud, increase timeout, check cable - Poor (<50): investigate hardware, consider flow control - Burst frequency warnings (>10% ratio) - Professional formatted output with section headers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- gen_octree: init -> initCapacity, deinit(allocator) - gen_radix_tree: remove unused variable - gen_skiplist_impl: ArrayList API fixes - gen_veb_tree: Zig 0.15 compatibility - cyrillic_guard: fix break expression, expand to full version (288 LOC) - README.md: fix doc paths - All tests passing φ² + 1/φ² = 3 | TRINITY
lru_cache_impl, octree, skiplist_impl, splay_tree, veb_tree, zenodo fixes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
arithmetic, burrows_wheeler, escape, leb128, lz77, rle, utf16, varint generators Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changed {s} to {d:.2} for f64 value in zenodo print output.
Fixes build error: expected optional type, found 'f64'.
(#435)
…nère, XOR cipher, UUID generator) (#435)
- Add TRI-27 Token & Staking section to README.md
- Document token commands: balance, stake, unstake, claim, wallet
- Add Coptic register mapping (t18-t22)
- Document APY formula (base 5% + lock bonus + staked bonus = capped at 20%)
- Fix Zig 0.15.x compatibility in tri_zenodo.zig
- Comment out code referencing non-existent zenodo_v21/v22 modules
- Add "not yet available" placeholder messages
- Fix Zig 0.15.x compatibility in tri_cloud.zig
- Fix error capture (catch |_| -> catch |_err|)
- Fix stdin API (getStdIn().read())
- Fix format strings ({} -> {s} for error names)
- Mark unused stderr_str with _
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fixed unused captures in catch blocks (changed |err| to |_|) - Removed unused stderr_str variable - Fixed getStdIn() -> getStdInInIo() for Zig 0.15 - Removed _ = prefix from if statement that was causing parse error (#435)
- Replace errorDescription(err) with @Errorname(err) for Zig 0.15 compatibility - Fix Child.run catch block to handle errors properly instead of returning void - Remove unused _ = allocator statements - Fix format specifiers in error messages
) README.md: - Fix src/tri-lang/emu/specs/tri27_isa.md → src/tri27/emu/specs/tri27_isa.md - Fix deploy/Dockerfile.tri → deploy/Dockerfile - Fix .ralph/RULES.md → .trinity/ralph/RULES.md - Fix .ralph/SUCCESS_HISTORY.md → .trinity/ralph/SUCCESS_HISTORY.md AGENTS.md: - Fix .ralph/ → .trinity/ralph/ directory paths src/tri/tri_zenodo.zig: - Fix unused function parameter in runV21Command (allocator → _) - Fix unused function parameter in runV22Command (allocator → _) src/tri/tri_cloud.zig: - Fix std.io.getStdIn() → std.io.getStdInHandle() (Zig 0.15 API) - Fix unused error capture in catch blocks (_|_ → _) - Fix format specifiers for errors ({} restored for anyerror type) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- V16: Statistical Significance (p-values, confidence intervals) - V16 Extensions: Enhanced experiment results - V19 ORCID: Author identification integration - V19 CFF: Citation File Format 1.2.0 generator - V19 OpenAlex: Work type classification + COAR notifications - V20 Stats: Advanced statistical methods Also: - Fix cyrillic_guard.zig for Zig 0.15 (ArrayList API, Utf8Iterator) - Fix tri_cloud.zig for Zig 0.15 (getStdin().reader(), catch blocks) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ed (#435) - V21 (Broader Impact) and V22 (Reproducibility) modules not yet created - Replaced calls with placeholder messages - TODO: Implement zenodo_v21_broader_impact.zig and zenodo_v22_reproducibility.zig Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- V21: Broader impact statements for NeurIPS/ICLR/MLSys 2025 - V22: Reproducibility checklist for conference submissions - Fixed Zig 0.15 ArrayList API (AlignedManaged, append, deinit, toOwnedSlice) - All tests passing
src/tri/tri_cloud.zig: - Fix std.io.getStdIn() → std.io.getStdInHandle() - Fix unused error captures in catch blocks src/tri/tri_zenodo.zig: - Fix unused function parameters in runV21Command/runV22Command Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Unified access to V16-V22 Zenodo modules - ScientificPublication with markdown export - Conference deadline tracking (NeurIPS/ICLR/MLSys 2025) - PaperPackage compliance scoring (80+ for submission) - All tests passing (3/3)
- BrowserRouter → HashRouter for GitHub Pages compatibility - URLs now: t27.ai/#/dashboard, t27.ai/#/tree - Fixes 404 errors on SPA routes without server config
- Export formats: Markdown, LaTeX, HTML, PDF metadata JSON - Conference templates: NeurIPS/ICLR/ICML/MLSys/AAAI/IJCAI 2025 - Word limit validation per conference - PaperBuilder for flexible paper construction - All tests passing (3/3)
- docs-check/Validate README Command Examples: switch from goto-bus-stop/setup-zig@v2 (missing 0.15.0) to mlugg/setup-zig@v2 with version 0.15.2 (consistent with ci.yml and brain-ci.yml) - docs-check/Check Documentation Links: add ignore patterns for known false-positive domains (zenodo.org 403, trinity.ai down, trinity-os.fly.dev ENOTFOUND, sciencedirect/acm.org 403, github discussions 404) - Fix Zig version in docs from 0.15.0 to 0.15.2 (actual release)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation improvements following best practices for Docusaurus documentation UX.
Changes (19 files, +178/-228 lines)
Critical Fixes
adr/template→adr/000-template, etc. to match actual filenamesIMPROVEMENTS_BEFORE_SCIENTIFIC_COLLABORATION.md(0 bytes)TRINITY_TAMOTCHI_STAGE_5_ADULT.md(typo in name, duplicate of TAMAGOTCHI version)Navigation & UX Improvements
SEO & Discoverability
Content Enhancement
Testing
These are documentation-only changes (Markdown + TypeScript sidebar config). To verify locally: