Skip to content

README.md

Latest commit

 

History

History
123 lines (100 loc) · 7.9 KB

README.md

File metadata and controls

123 lines (100 loc) · 7.9 KB
Raw

docs/ — Active Fedference documentation hub

Operational rulebook for the Active Fedference project. Enforcement varies by file — see AGENTS.md's REQUIRED vs AESTHETIC table for what is gate-checked versus convention.

Apply the software: application-guide.md · ../examples/README.md

Contract & identity: ../ISA.md · ../README.md · ../STANDALONE.md

Current public release v1.0.4: DOI 10.5281/zenodo.21972644 · GitHub release · public GitHub repository · Zenodo record · prior v1.0.3 record · v1.0.2 record · v1.0.1 record · v0.1.0 record

Choose a path

I want to… Start here
Aggregate my own labeled categorical posteriors application-guide.md; ../examples/README.md, example 05
Compare the three server rules ../examples/README.md, example 02
Exercise direct, process, socket, and replay boundaries ../examples/README.md, example 03
Produce and verify an application receipt ../examples/README.md, example 05; ../src/fedference_cli/README.md
Produce and verify a registered research receipt ../examples/README.md, example 04; ../src/fedference_cli/README.md
Understand the mathematical scope core/conceptual-foundations.md
Contribute software or documentation development/quickstart.md; development/modularity.md
Reproduce the manuscript surfaces manuscript/rendering_pipeline.md
Audit a release boundary reference/verification-commands.md; reference/zenodo-release.md

Subfolders

Folder Purpose
core/ Science narrative, architecture, experiments & artifacts
development/ Agent rules, quickstart, modularity, testing, style
manuscript/ PDF/web pipeline, accessibility boundary, tokens & labels
operations/ Output layout, troubleshooting, FAQ
reference/ Verification, API/schema stability, and Zenodo release boundary
research/ Indexed scholarship, claim, statistical, visual, complexity, RedTeam, runtime/composability, and CLI/orchestration audits
security/ Runtime/development trust boundaries, abuse paths, mitigations, and no-claim constraints
todo/ Scoped forward roadmap pages linked from TODO.md

Read order (new contributors)

  1. ../README.md — project pitch and run commands
  2. application-guide.md — adapt the software to caller-owned posteriors
  3. ../examples/README.md — deterministic public-API example ladder
  4. development/quickstart.md — contributor and reviewer-snapshot reproduction
  5. core/conceptual-foundations.md — why this project exists
  6. operations/faq.md — common questions

Read order (agents)

  1. development/agent_instructions.md — repository editing rules and visual QA
  2. core/architecture.md — layer boundaries
  3. development/testing_philosophy.md — zero mocks + coverage
  4. development/modularity.md — before adding software, scripts, reports, figures, or documentation
  5. manuscript/rendering_pipeline.md — before editing outputs
  6. manuscript/accessibility.md — before accessibility or publication-surface claims
  7. development/style_guide.md — before editing source
  8. manuscript/tokens-and-labels.md — before editing manuscript prose
  9. reference/zenodo-release.md — before reserving, updating, uploading, or publishing a DOI deposition

Reader paths

Before modifying…

Task Read first
src/fedference/* core/architecture.md, development/style_guide.md
src/fedference_cli/*, src/analysis/*, or src/publication/* development/modularity.md, core/architecture.md
tests/* development/testing_philosophy.md
manuscript/*.md manuscript/tokens-and-labels.md, ../manuscript/SYNTAX.md
scripts/* core/architecture.md, ../scripts/AGENTS.md
examples/* ../examples/README.md, development/modularity.md
Federation transport / deployment security/active_fedference-threat-model.md, todo/true-multi-machine-federation.md
Pipeline / output/ operations/output-layout.md
Roadmap / TODO scope todo/README.md, ../TODO.md

Contributor verification

uv run --locked --extra dev pytest tests/ \
  --cov=src --cov-fail-under=90 -q

Full probe list: reference/verification-commands.md.

Mermaid diagrams are deliberately kept in the Markdown source for GitHub and local readers. Every block in README.md and docs/ has one non-empty accTitle, one non-empty accDescr, quoted punctuation-bearing labels, and an immediately adjacent plain-language text equivalent. The validator discovers the live diagram count rather than relying on a fixed inventory. Every block must pass the static contract and, before a release render, an actual Mermaid CLI SVG probe:

uv run --locked python scripts/validate_mermaid.py
uv run --locked python scripts/validate_mermaid.py --render --renderer npx \
  --output-dir .tmp/mermaid-render

Index

Technical file inventory and REQUIRED vs AESTHETIC table: AGENTS.md.