Rewrite experiment docs with TeX-grounded mathematical context

Author: flengyel

docs/Gemini_hallicination.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/Gemini_hallicination.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Critically checks conjectural statements against the proven DSTM framework and identifies mismatches between heuristic claims and manuscript-level results.
+
+## Theoretical Anchors
+
+- tex/introduction.tex (overall DSTM program and classification objective).
+- tex/combinatorics.tex (strict algebraic n-hypergroupoid criterion k = n).
+- tex/dichotomy.tex (filler uniqueness vs non-uniqueness regimes).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/Gemini_hallicination.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Diagnostic comparisons in console output documenting where claims fail or require proof-level support.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.

docs/atlas_cospectral_scan.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/atlas_cospectral_scan.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Computes graph-derived simplicial statistics (including boundary-rank style invariants) for cospectral/non-isomorphic comparisons and structural scans.
+
+## Theoretical Anchors
+
+- tex/horns.tex (kernel-support interpretation of omitted faces).
+- tex/combinatorics.tex (rank counting framework and inclusion-exclusion viewpoint).
+- tex/generated_subobjects.tex (realization matrices and rank-loss/collision perspective).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/atlas_cospectral_scan.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Enumerations, rank distributions, cospectral pair comparisons, and optional saved summaries.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.

docs/bdry_network_experiment1.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/bdry_network_experiment1.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Explores ML-style training behavior under simplicial boundary/degeneracy-inspired transformations and compares optimization behavior across configurations.
+
+## Theoretical Anchors
+
+- tex/normalization.tex (decomposition into normalized and degenerate components).
+- tex/combinatorics.tex (rank behavior and boundary-related structure in degrees).
+- tex/equivariant_homotopy.tex (contractibility perspective motivating robustness checks).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/bdry_network_experiment1.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Training/validation statistics, loss curves, and optional plot artifacts for comparative runs.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.

docs/boundary_augmented_network.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/boundary_augmented_network.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Explores ML-style training behavior under simplicial boundary/degeneracy-inspired transformations and compares optimization behavior across configurations.
+
+## Theoretical Anchors
+
+- tex/normalization.tex (decomposition into normalized and degenerate components).
+- tex/combinatorics.tex (rank behavior and boundary-related structure in degrees).
+- tex/equivariant_homotopy.tex (contractibility perspective motivating robustness checks).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/boundary_augmented_network.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Training/validation statistics, loss curves, and optional plot artifacts for comparative runs.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.

docs/consolidated_experiment.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/consolidated_experiment.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Performs targeted computational checks of combinatorial identities and structural invariants on explicit tensor families.
+
+## Theoretical Anchors
+
+- tex/horns.tex (missing-index characterization and face-kernel basis).
+- tex/combinatorics.tex (rank and finite-difference formulas).
+- tex/normalization.tex (decomposition through Moore filler map).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/consolidated_experiment.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Consistency checks, discrepancy reports, and compact experiment summaries.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.

docs/consolidated_experiment_with_n01.md

@@ -2,31 +2,47 @@
 
 ## Source
 
-$s
+```text
+experiments/consolidated_experiment_with_n01.py
+```
 
 ## Type
 
 Python script
 
-## Purpose
+## Research Goal
 
-This document tracks the experiment script $s and its role in exploratory simplicial-tensor workflows.
+Performs targeted computational checks of combinatorial identities and structural invariants on explicit tensor families.
+
+## Theoretical Anchors
+
+- tex/horns.tex (missing-index characterization and face-kernel basis).
+- tex/combinatorics.tex (rank and finite-difference formulas).
+- tex/normalization.tex (decomposition through Moore filler map).
+
+## Typical Workflow
+
+1. Configure shape/order/parameter choices directly in the script.
+2. Run the script to evaluate identities or invariants associated with its target phenomenon.
+3. Compare printed or saved outputs against the theorem-level expectations listed above.
 
 ## How To Run
 
-`ash
+```bash
 python experiments/consolidated_experiment_with_n01.py
-`
+```
 
 ## Inputs
 
-- Parameters and constants defined directly in the script.
-- Local package modules from src/simplicial_tensors.
+- Tensor shape data or graph/permutation objects defined in-script.
+- The core simplicial_tensors implementation in src/simplicial_tensors.
+- Optional scientific/python ecosystem dependencies required by the script.
 
 ## Outputs
 
-- Console output and, depending on script logic, generated artifacts (for example plots or intermediate files).
+- Consistency checks, discrepancy reports, and compact experiment summaries.
+
+## Interpretation Guidance
 
-## Notes
+Use this script as computational evidence for manuscript-level claims, not as a standalone proof. Cross-check discrepancies against the cited TeX sections and their formal statements.
 
-- This script lives under xperiments/ and is research-oriented rather than part of the stable package API.