Monoflow - Monolex Docs

Monoflow is the analysis layer that unifies all Mono tools. It reads from monogram (code), monogit (git), monomento (docs), and watcher/diff databases to discover hidden patterns, measure work quality, and connect code state to SMPC philosophy.

Quick Start

# Full stack refresh (one command)
niia reindex

# Or step by step:
monogram reindex .
monomento index . --project
monogit index --symbols -n 5000 --all
monoflow analyze

# Explore
monoflow insights           # 21 insight categories
monoflow search "query"     # 4-DB unified search
monoflow gaps               # What's missing
niia insights               # With consciousness echo

Commands

Analysis

Command	Description
`analyze`	Compute topics + cochange → save to DB
`analyze --full`	Reindex all lower tools first, then analyze
`topics`	Topic clusters from last analyze
`map`	Topic relationship map + hub centrality
`health`	Codebase coupling health score
`insights`	21 insight categories across all 4 DBs
`search <query>`	Unified 4-DB search with 0-10 scoring
`gaps`	What’s missing: phantoms, undocumented, drift, disconnects
`weights`	View/set quality delta weights

Drill Commands

Command	Description
`phantom <symbol>`	Trace a symbol’s lifecycle: alive? → last seen? → docs? → renames?
`drift <file>`	Which files stopped co-changing with this one
`chain <symbol>`	3-DB symbol drill: code + git + docs

Temporal

Command	Description
`timeline <file>`	File’s temporal flow (saves + commits + watches)
`recent`	All recent events
`impact <file>`	Diff + symbols + chain callers
`correlate`	Time-window activity clusters
`cochange`	Files that always change together

Topic Views

Command	Description
`topic-flow` / `tf`	When topics started, lived, ended
`timeline-topics` / `tt`	Topics × days heatmap
`file-topics` / `ft`	File’s topic history over time

Git Analytics

Command	Description
`branches`	M:N relationships
`branches --evolution`	Lifecycle + timeline + velocity
`branches --graph`	Fork points + ahead/behind + lineage
`symbol-graph` / `sg`	Hidden branch connections via shared symbols
`dashboard`	Project overview
`authors`	Author activity patterns

Repo Management

Command	Description
`link <path>`	Link a docs repo
`links`	Show linked repos
`status`	DB connection status

Insights (21 categories)

monoflow insights discovers hidden patterns by cross-querying all databases:

Code Analysis (from monogram)

Category	What it finds
CSS dead tokens	Defined but never used
CSS missing tokens	Used but not defined
Cross-language bridges	RS↔TS function name overlap
Cross-language chains	Symbols used across 3+ languages
Broken chains	Called but not defined
Call chain hubs	High-connectivity functions
Repo dependency graph	Auto-detected from Cargo.toml

Documentation Analysis (from monomento)

Category	What it finds
Doc reference chains	Long document reference paths
Doc bridges	Similar documents without explicit links
Hub docs	Most connected documents
Doc-code convergence	Docs mentioning code but no refs
Doc-section mappings	Which doc sections describe which code

Git History Analysis (from monogit)

Category	What it finds
Stale docs	Code changed, doc didn’t follow
Naming drift	camelCase vs snake_case over time
Chain growth	Functions gaining callers
Code+doc commits	Both code and docs changed together
Temporal drift	File pairs that stopped co-changing
Phantom symbols	In docs but gone from code
Topic knowledge gaps	Active code with no documentation

Quality Delta (9 signals)

Instead of just measuring how much work was done (quantity), monoflow measures work quality through 9 signals derived from commit patterns.

Converging signals (positive — things coming together)

Signal	Range	Meaning
temporal	−0.20 to +0.70	Steady 1-10min commit gaps
convergence	0.00 to +1.00	Code+doc changed in same commit
commit_type	−0.50 to +0.50	feat ratio − fix ratio
structural	0.00 to +0.50	New files + refactors
thinking	0.00 to +0.20	10-30min deliberate gaps
topic_focus	−0.30 to +0.20	Low topic switching = focused

Diverging signals (negative — things falling apart)

Signal	Range	Meaning
divergence	−0.50 to 0.00	Code changing, docs not following
churn	−0.40 to 0.00	Same file 3+ times in 1hr
streak	−0.40 to 0.00	Consecutive fix commits

Scenarios

Based on signal combination, monoflow detects the work scenario:

Scenario	Condition	Meaning
Struggle	high churn + negative type	Debugging pain
Exploration	low temporal + positive type	Trying things
ManagedFlow	steady gaps + positive type	Productive rhythm
Convergence	high convergence	Code and docs aligning
StructuralImprovement	structural + low churn	Architecture improving

Configurable Weights

monoflow weights                    # View all weights + signal descriptions
monoflow weights temporal=0.25     # Change a weight
monoflow weights --reset            # Reset to defaults

Config file: ~/.monolex/config/quality-weights.json

SMPC Combined

The quality delta feeds into the SMPC combined formula:

combined = spec_chaos((1 − state) / (1 + delta))

Where state is the layer chaos score and delta is the quality delta.

  SMPC Combined (state × management momentum):
    rhythm          0.728 ↑0.29 → 0.825  Managed → Simple
    documentation   0.386 ↑0.22 → 0.666  Part → Managed
    overall         0.519 ↑0.28 → 0.726  Managed
    scenario: ManagedFlow  quality delta: 0.290
    converging: gaps:+0.47  think:+0.10  type:+0.10
    diverging:  div:-0.50  churn:-0.40  streak:-0.23

Layer Chaos

Each codebase aspect gets a spec_chaos score (1.0 = simple, 0.0 = chaotic):

Layer	What it measures	SMPC States
css	CSS token management	dead/missing ratio
documentation	Doc freshness	stale doc severity × time weight
structural	Code coupling	call chain hub complexity
rhythm	Commit regularity	session pattern distribution
temporal	File relationship stability	drift pair analysis

SMPC states from SPEC_CHAOS_MATHEMATICAL_CODEX:

Chaos: spec_chaos < 0.3
Part: spec_chaos 0.3-0.5
Managed: spec_chaos 0.5-0.8
Simple: spec_chaos > 0.8

Reindex Cascade

Each layer refreshes everything below it:

niia reindex               # Full: monogram → monomento → monogit → knowledge → monoflow
work-wiki reindex          # Self: monoflow --full → knowledge index
monoflow analyze --full    # Lower: monogram → monomento → monogit → topics → insights

Pre-computed Analysis

Heavy computations run at index time, not query time:

monogram.db:  analysis_css, analysis_hubs  (computed at monogram reindex)
monogit.db:   analysis_drift, analysis_rhythm, analysis_quality_delta  (at monogit index)

Monoflow insights reads pre-computed tables for instant results.

Stack

niia          consciousness + orchestration
  ↕
work-wiki     knowledge layer (550K+ entries)
  ↕
monoflow      temporal flow + cross-DB analysis + quality delta
  ↕
monogram      monogit        monomento
(code)        (git)          (docs)

Per-Repo Database

Each repository gets its own analysis database:

~/.monolex/monoflow/{name}-{hash}.db

Analysis results from different repositories never mix.

Documentation Index

​Quick Start

​Commands

​Analysis

​Drill Commands

​Temporal

​Topic Views

​Git Analytics

​Repo Management

​Insights (21 categories)

​Code Analysis (from monogram)

​Documentation Analysis (from monomento)

​Git History Analysis (from monogit)

​Quality Delta (9 signals)

​Converging signals (positive — things coming together)

​Diverging signals (negative — things falling apart)

​Scenarios

​Configurable Weights

​SMPC Combined

​Layer Chaos

​Reindex Cascade

​Pre-computed Analysis

​Stack

​Per-Repo Database