docs: centralize canonical TNFR documentation

Intent: improve structural coherence and traceability across the repository documentation.

Operators involved: Coherence, Contraction, Self-organization.

Affected invariants: nodal equation integrity, grammar compliance, structural metrology, reproducible dynamics.

Key changes: centralize architecture and theory indexes; remove obsolete audit and package documents; add strict documentation checks and MkDocs configuration; correct package claims and installation tests.

Expected risks/dissonances: removed historical material is preserved in Git history; active references were verified.

Metrics: 903 internal references valid; strict documentation build passes; 45 focused tests pass.

Author: TNFR AI Agent

.github/WORKFLOWS.md

@@ -1,140 +1,39 @@
 # GitHub Actions Workflows
 
-This document describes the CI/CD workflows configured for this repository.
-
-## Active Workflows
-
-### Core Development Workflows
-
-#### 1. CI (`ci.yml`)
-**Triggers:** Push and PR to main/master branches  
-**Purpose:** Core continuous integration testing and quality checks  
-**Jobs:**
-- **Format check**: Runs pre-commit hooks (black, isort, pydocstyle)
-- **Type check and static analysis**: Runs flake8, mypy, pyright, vulture, and language policy enforcement
-- **Changelog fragments**: Enforces changelog fragments for PRs
-- **Tests**: Runs pytest across Python 3.9-3.13 with coverage reporting
-
-**Status:** ✅ Working (has legitimate doctest failures in codebase, not workflow issues)
-
-#### 2. Docs (`docs.yml`)
-**Triggers:** Push and PR to main branch  
-**Purpose:** Build and validate documentation  
-**Jobs:**
-- Build MkDocs site with strict mode
-- Run Sphinx doctests
-- Perform link checking
-
-**Status:** ✅ Working (has legitimate doctest failures in codebase, not workflow issues)
-
-### Security Workflows
-
-#### 3. Dependency Vulnerability Audit (`pip-audit.yml`)
-**Triggers:** Push/PR to main/master, weekly schedule (Monday 5 AM UTC), manual dispatch  
-**Purpose:** Scan Python dependencies for known vulnerabilities (PyPA Advisory Database)  
-**Jobs:**
-- Install all project dependencies
-- Run pip-audit against installed packages
-- Upload JSON report artifact
-- Fail build if vulnerabilities detected
-
-**Status:** ✅ Working correctly
-
-**Note:** This is the single retained automated vulnerability scanner. It runs
-as a CI check and never creates branches or pull requests. The previous CodeQL
-and Bandit/Semgrep (SAST Lint) workflows and the Dependabot version-update
-configuration were removed to eliminate automated branch/alert noise. Secret
-scanning and push protection remain enabled at the repository settings level
-(notification-only, no branches generated).
-
-### Quality Assurance Workflows
-
-#### 6. Reproducibility Check (`reproducibility.yml`)
-**Triggers:** Push/PR to main/master, manual dispatch  
-**Purpose:** Verify benchmark reproducibility (TNFR canonical requirement)  
-**Jobs:**
-- Run benchmarks twice with same seed
-- Compare manifest checksums
-- Verify identical results
-
-**Status:** ✅ Working correctly
-
-#### 7. Performance Regression (`performance-regression.yml`)
-**Triggers:** PRs to main/master, manual dispatch  
-**Purpose:** Detect performance degradations  
-**Jobs:**
-- Run performance regression test suite
-- Mark slow tests appropriately
-
-**Status:** ✅ Working correctly
-
-#### 8. Verify Internal References (`verify-references.yml`)
-**Triggers:** Push/PR affecting markdown/notebook files  
-**Purpose:** Validate internal documentation links  
-**Jobs:**
-- Scan 985+ internal references
-- Report broken links
-
-**Status:** ⚠️ Working but reports 75 broken links (codebase issue, not workflow)
-
-### Infrastructure Workflows
-
-#### 9. Lint Workflows (`lint-workflows.yml`)
-**Triggers:** Push/PR affecting workflows, tools, or scripts  
-**Purpose:** Validate workflow configurations  
-**Jobs:**
-- Check for invalid Bandit format usage (SARIF not supported)
-- Verify bandit_to_sarif.py converter exists
-
-**Status:** ✅ Working correctly
-
-#### 10. Release (`release.yml`)
-**Triggers:** Push to main, manual dispatch  
-**Purpose:** Automated semantic release process  
-**Jobs:**
-- **Prepare**: Detect next version, compile changelog, apply tags
-- **Publish**: Build distributions, sign with GPG, publish to PyPI, create GitHub release
-
-**Status:** ✅ Working correctly (intentionally skips when no release needed)
-
-## Removed Workflows
-
-The following workflows were removed during cleanup:
-
-### 1. `bandit.yml` (Removed)
-**Reason:** Duplicate functionality - Bandit already runs in `sast-lint.yml`
-
-### 2. `black-duck-security-scan-ci.yml` (Removed)
-**Reason:** Requires paid Black Duck service with configuration not available in repository
-
-### 3. `security-dashboard.yml` (Removed)
-**Reason:** Optional aggregator workflow with configuration issues; individual security scans (CodeQL, SAST, pip-audit) already provide comprehensive coverage
-
-## Workflow Best Practices
-
-1. **Concurrency Control**: All workflows use `concurrency` groups with `cancel-in-progress: true` to save CI resources
-2. **Caching**: Python dependencies and pip are cached to speed up builds
-3. **Matrix Testing**: CI tests across Python 3.9-3.13 to ensure compatibility
-4. **SARIF Integration**: Security workflows upload results to GitHub Security tab
-5. **Artifact Preservation**: Important outputs (reports, logs) are uploaded as artifacts
-
-## Known Issues
-
-These issues exist in the codebase, not in workflow configurations:
-
-1. **Doctest Failures**: 
-   - Files: `docs/source/api/api_mapping.rst`, `docs/source/how_to_reproduce_results.rst`
-   - Cause: Unexpected warnings and validation errors
-   - Impact: CI and Docs workflows report failures
-
-2. **Broken Documentation Links**: 
-   - 75 broken internal references
-   - Common patterns: missing API pages, moved/renamed files
-   - Impact: Verify Internal References workflow reports failures
-
-## Maintenance Notes
-
-- All workflows follow TNFR canonical requirements (reproducibility, traceability, English-only)
-- Security workflows run on schedule to catch newly disclosed vulnerabilities
-- Release workflow requires semantic commit messages for version bumping
-- No workflow credentials are committed to the repository (use GitHub Secrets)
+This page describes workflow intent. Workflow YAML is the source of truth for
+triggers, matrices, permissions, and commands.
+
+## Active validation
+
+| Workflow | Responsibility |
+| --- | --- |
+| `ci.yml` | Formatting, lint, advisory type analysis, changelog policy, and tests on Python 3.10-3.13 |
+| `docs.yml` | Internal paths and fragments, documentation integrity, strict MkDocs build, and Pages publication from main |
+| `verify-references.yml` | Independent internal-reference validation for Markdown changes |
+| `tests.yml` | Additional test execution |
+| `reproducibility.yml` | Repeated seeded benchmark comparison |
+| `performance-regression.yml` | Performance regression checks |
+| `pip-audit.yml` | Dependency vulnerability audit |
+| `release.yml` | Versioned release and publication |
+
+## Documentation publication
+
+There is one documentation build and deployment workflow:
+
+1. install the project with the `docs` extra;
+2. validate local Markdown targets and GitHub-style fragments;
+3. run executable documentation integrity checks;
+4. stage canonical repository sources with `scripts/prepare_docs.py`;
+5. build MkDocs with strict mode;
+6. publish the exact `site/` artifact on pushes to `main`.
+
+Pull requests build and validate the same site without publishing it.
+
+## Maintenance rules
+
+- Keep supported Python versions synchronized with `pyproject.toml`.
+- Keep commands in this page descriptive; copy exact command details only when
+  they are stable public interfaces.
+- Treat advisory jobs as advisory in both prose and YAML.
+- Do not report workflow health or finding counts as permanent facts here.
+- Update this page when a workflow is added, removed, or changes purpose.

.github/agents/my-agent.md

@@ -556,7 +556,7 @@ program history** (the full milestone/gap/branch threads live in the notes).
 | **REMESH-∞ closure** | The 13-operator catalog is closed under the `τ_g → ∞` limit (N15, Branch A); universality is structural/operational, not spectral. | [REMESH_INFINITY_DERIVATION.md](theory/REMESH_INFINITY_DERIVATION.md) |
 | **TNFR-Navier–Stokes** | The two-face reading: incompressible NS is first-order, so its *linear* part is the **diffusive (over-damped) projection** of the separate graph-wave model (`ν_f = ν`; `verify_diffusive_face` VALID for every physical viscosity) — blow-up is a purely **nonlinear `K_φ` cascade** (the vortex-stretching VAL source), not a linear resonance. Measured: peak enstrophy debt grows with Re at matched `τ_str = ν·t` (bounded at fixed Re — the diffusive face regularises); the `Re → ∞` cascade bound = Clay, **open**. Closes nothing. | [TNFR_NAVIER_STOKES_RESEARCH_NOTES.md](theory/TNFR_NAVIER_STOKES_RESEARCH_NOTES.md) |
 | **Number theory** | Primality as `ΔNFR = 0` (canonical **unit** coefficients, §4.2 coefficient independence); arithmetic structural triad; the arithmetic network as an NFR (multinodal topology + emergent symplectic geometry); the cyclotomy law `s_k(p) = gcd(k, p−1) + 1` (proved), read as the **arithmetic pulse** (the residue-NFR's tone-count — a prime is its most degenerate chord). | [TNFR_NUMBER_THEORY.md](theory/TNFR_NUMBER_THEORY.md) |
-| **Structural research program (R1–R9)** | Nine internal lines on the arithmetic/spectral dynamics, refined by the post-review roadmap (N00–N13): symmetry-sector observability with **word-composition closure and pointed selectors** (R1, N06/N07 **derived**; cross-operator cache leak fixed, N01); the arithmetic pulse recurrence `gcd(k,p−1)+1` plus **amplitudes `= m_λ/n`** (R2, N12 **derived**); CRT as U5 synthesis (R3, exact Kronecker); the projective p-adic tower — transport exact, **REMESH is a morphism not an operator** (R4/N09, the static lift fails only the temporal echo); finite/Gaussian fields with the exact **trace-collision** character formula (R5, N10; type detection still k-sensitive); controlled additive theory (R6, additive reading **= Fourier**, constructive negative); the arithmetic-pressure audit — sufficient, functionally independent, **primality-redundant**, completeness open (R7/N02); operator certification plus a **structural-morphism taxonomy derived from the nodal equation** (R8/N08, 6 of 7 kinds emerge as nodal-flow transports — no 14th operator); directed non-normal dynamics — metric layer, scalar-`ν_f` **clock-change theorem**, transient U2/U6 (per-node contraction; the ambient `>1` is the `‖Q‖` projection artifact) and the heterogeneous-`ν_f` boundary (R9, N03–N05/N13). The canonical U2 metric stays **open** and U2/U6 are **unmodified**. None closes an open problem. | [RESEARCH_R1_R9_HANDOFF_2026-09-05.md](theory/RESEARCH_R1_R9_HANDOFF_2026-09-05.md) |
+| **Structural research program (R1–R9)** | Nine internal lines on arithmetic and spectral dynamics: observability, arithmetic pulse, CRT synthesis, p-adic transport, finite fields, additive reduction, arithmetic pressure, operator certification and directed non-normal evolution. Exact, measured, negative and open results are separated in the program index. | [STRUCTURAL_RESEARCH_PROGRAM.md](theory/STRUCTURAL_RESEARCH_PROGRAM.md) |
 | **Millennium reformulations** | P vs NP, BSD, Hodge, Yang–Mills: TNFR-internal structural reformulations and diagnostics — none a proof. | `theory/TNFR_*_RESEARCH_NOTES.md` |
 
 **Honest scope, global**: these programs produce TNFR-internal structural results and
@@ -590,7 +590,7 @@ Navier–Stokes regularity, or any Millennium problem.
   (R2 rank + amplitudes), `crt_multiscale.py` (R3), `padic_tower.py` / `remesh_audit.py`
   (R4 transport + REMESH audit), `finite_fields.py` / `trace_collisions.py` (R5),
   `arithmetic_pressure.py` (R7), `operator_certificates.py` (R8). Ledger:
-  [RESEARCH_R1_R9_HANDOFF_2026-09-05.md](theory/RESEARCH_R1_R9_HANDOFF_2026-09-05.md).
+  [STRUCTURAL_RESEARCH_PROGRAM.md](theory/STRUCTURAL_RESEARCH_PROGRAM.md).
 - **SDK** — [src/tnfr/sdk/](src/tnfr/sdk/): `simple.py` (`TNFR.create(...)`, tetrad,
   conservation, substrate, integrity, audit, `nfr()` whole-NFR read-out,
   `nodal_state`/`nodal_scan` micro-NFR), `fluent.py` (`auto_optimize()`). The shared

.github/workflows/deploy-docs.yml

@@ -1,62 +1,62 @@
-name: Build and Deploy Documentation (DISABLED)
+name: Documentation
 
-# DISABLED: Documentation is now built locally only. This workflow stays valid
-# but only runs on manual dispatch (a workflow with no 'on:' trigger is invalid
-# and reports a startup failure on every push). To re-enable automatic builds,
-# add the push / pull_request triggers under 'on:' below.
 on:
+  push:
+    branches: [main]
+    paths:
+      - '**.md'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - 'scripts/check_documentation.py'
+      - 'scripts/prepare_docs.py'
+      - 'scripts/verify_internal_references.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**.md'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - 'scripts/check_documentation.py'
+      - 'scripts/prepare_docs.py'
+      - 'scripts/verify_internal_references.py'
+      - '.github/workflows/docs.yml'
   workflow_dispatch: {}
 
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
 jobs:
-  build-deploy:
+  build:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
-
-      - name: Install dependencies
+          cache: pip
+      - name: Install project and documentation dependencies
+        run: python -m pip install --upgrade pip && python -m pip install '.[docs]'
+      - name: Verify documentation sources
         run: |
-          python -m pip install --upgrade pip
-          pip install -r docs/requirements.txt
-
-      - name: Sync README files
-        run: |
-          python scripts/sync-readme-docs.py
-
-      - name: Build docs
+          python scripts/verify_internal_references.py --ci
+          python scripts/check_documentation.py
+      - name: Build canonical site
         run: |
-          mkdocs build
-
-      - name: Deploy to GitHub Pages
-        if: github.ref == 'refs/heads/main'
+          python scripts/prepare_docs.py
+          python -m mkdocs build --strict
+      - name: Deploy main documentation
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site
+          publish_branch: gh-pages
           force_orphan: true
-          commit_message: "docs: deploy MkDocs site (${GITHUB_SHA})"
-
-  link-check:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.11'
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install mkdocs mkdocs-material mkdocs-redirects
-      - name: Build (no deploy) & basic link check
-        run: |
-          mkdocs build
-          echo "(Basic build complete - consider adding lychee for deeper link checking)"
+          user_name: github-actions[bot]
+          user_email: github-actions[bot]@users.noreply.github.com
+          commit_message: docs publish ${{ github.sha }}

.github/workflows/docs.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.9'
+          python-version: '3.10'
 
       - name: Verify internal references
         run: |

.github/workflows/verify-references.yml

@@ -6,6 +6,7 @@ dist/
 build/
 site/
 docs/_build/
+build/docs-source/
 *.egg-info/
 *.egg
 .semantic_release/
@@ -86,4 +87,4 @@ logs/
 
 # Local-only modules (not published to GitHub)
 crypto/
-publish/
+publish/