# template_pools_rules_tools

**Pools, Rules, and Tools: A Template-Integrated Resource Architecture**

Run via the template monorepo from the repository root with `uv run python scripts/…`
or project-local scripts under `projects/templates/template_pools_rules_tools/scripts/`.
Copy `manuscript/config.yaml.example` to `manuscript/config.yaml` for forkable
configuration. Preserve template integrity when forking this exemplar into a
standalone checkout.

A meta-project exemplar demonstrating the integration of three top-level resource directories and four public tool exemplars:

| Directory | Role |
|---|---|
| `fonds/` | Stable data resource pools (bibliographies, contacts, datasets) |
| `tools/` | Executable tool entry points (code executor, model, validator, skill) |
| `rules/` | Soft (prompt-like) and strong (formal) rule specifications |

## Purpose

This project shows agents and developers how to:

1. **Read fonds** — load bibliographic references, contacts, and dataset metadata from `fonds/templates/`
2. **Apply rules** — discover and parse soft guidelines and strong constraint schemas from `rules/templates/`
3. **Invoke tools** — enumerate tool manifests and validate entrypoint scripts from `tools/templates/`
4. **Integrate all three** — orchestrate a combined validation and reporting pipeline

## Structure

```
template_pools_rules_tools/
├── src/
│   ├── type_defs.py           # All TypedDict definitions — edit here first
│   ├── fonds_reader.py        # Read fonds from fonds/templates/
│   ├── rules_applier.py       # Load and apply soft rules from rules/templates/
│   ├── strong_rule_evaluator.py  # Evaluate strong (hard-constraint) rules
│   ├── tools_invoker.py       # Discover tools from tools/templates/
│   ├── integration.py         # Integration orchestrator; generate_figure_data()
│   ├── figures.py             # Figure façade and shared manuscript figures
│   ├── cover_figure.py        # Cover-art renderer
│   ├── rule_hierarchy_figure.py # Rule-hierarchy renderer
│   └── __init__.py            # Re-exports all public symbols
├── scripts/
│   ├── 01_validate_sources.py       # Validate all sources exist and are well-formed
│   ├── 02_run_integration.py        # Run the full integration demo
│   ├── 03_generate_manuscript.py    # Generate manuscript variables
│   ├── 04_validate_strong_rules.py  # Validate strong-rule compliance
│   ├── 05_generate_figures.py       # Render the manuscript figure set
│   └── z_generate_manuscript_variables.py  # Resolve manuscript tokens
├── tests/
│   ├── test_fonds_reader.py
│   ├── test_rules_applier.py
│   ├── test_strong_rule_evaluator.py
│   ├── test_tools_invoker.py
│   ├── test_integration.py
│   ├── test_figures.py
│   ├── test_property_based.py
│   ├── test_manuscript_variables.py
│   ├── test_coverage_extras.py
│   └── test_generate_figures_script.py
└── manuscript/
    ├── config.yaml, config.yaml.example
    ├── 00_frontmatter.md … 07_conclusion.md
    ├── preamble.md, references.bib
    └── figures/
```

## Quick Start

From the repository root:

```bash
# Run tests
uv run pytest projects/templates/template_pools_rules_tools/tests/ -v

# Validate sources
uv run python projects/templates/template_pools_rules_tools/scripts/01_validate_sources.py

# Run integration demo
uv run python projects/templates/template_pools_rules_tools/scripts/02_run_integration.py
```

## When to use this template

Use this project when you need to:

- **Demonstrate** how a research project integrates multiple resource directories (fonds, tools, rules) in a single pipeline
- **Validate** that your fonds, tools, and rule infrastructure modules are correctly wired and discoverable
- **Onboard** new teams to the three-resource architecture with a concrete, runnable example
- **Test** cross-cutting concern integration where fonds supply data, rules govern validation, and tools execute transforms
- **Extend** the architecture by adding new resource types; copy this project as a starting point for integration testing

This template is ideal for platform teams, CI engineers, and infrastructure maintainers who need a self-validating meta-project that exercises all three resource layers without coupling to a specific domain science.

## Publication and rendering

<!-- PUBLISHING-STATUS:START (generated by infrastructure.publishing.status_report) -->
**Pools, Rules, and Tools: A Template-Integrated Resource Architecture** · v1.0.0 · Daniel Ari Friedman

Concept DOI: [10.5281/zenodo.21298888](https://doi.org/10.5281/zenodo.21298888) | Version DOI: [10.5281/zenodo.21298889](https://zenodo.org/records/21298889) | Repository: [docxology/template_pools_rules_tools](https://github.com/docxology/template_pools_rules_tools)

Publishing surface — 20 platforms, 2 published:

| Platform | Tier | Status | Reference | Credentials |
| --- | --- | --- | --- | --- |
| zenodo | first-class | ✅ published | [10.5281/zenodo.21298888](https://doi.org/10.5281/zenodo.21298888) | `ZENODO_API_TOKEN` |
| github | first-class | ✅ published | [docxology/template_pools_rules_tools](https://github.com/docxology/template_pools_rules_tools) | `GITHUB_TOKEN` |
| arxiv | first-class | ⚪ available | — | — |
| pypi | first-class | ⚪ available | — | `PYPI_TOKEN`, `TESTPYPI_TOKEN` |
| ipfs_pinata | first-class | ⚪ available | — | `PINATA_JWT` |
| ipfs_web3storage | first-class | ⚪ available | — | `WEB3_STORAGE_TOKEN` |
| software_heritage | first-class | ⚪ available | — | — |
| github_pages | first-class | ⚪ available | [docxology/template_pools_rules_tools](https://github.com/docxology/template_pools_rules_tools) | `GITHUB_TOKEN` |
| cloudflare_pages | first-class | ⚪ available | — | `CLOUDFLARE_API_TOKEN` |
| netlify | first-class | ⚪ available | — | `NETLIFY_AUTH_TOKEN` |
| huggingface_hub | first-class | ⚪ available | — | `HUGGINGFACE_TOKEN`, `HF_TOKEN` |
| osf | first-class | ⚪ available | — | `OSF_TOKEN` |
| amazon_kdp | documented | 🟡 planned | — | `AMAZON_KDP_EMAIL`, `AMAZON_KDP_PASSWORD` |
| google_play_books | documented | 🟡 planned | — | `GOOGLE_PLAY_BOOKS_SERVICE_ACCOUNT_JSON` |
| gumroad | documented | 🟡 planned | — | `GUMROAD_ACCESS_TOKEN` |
| leanpub | documented | 🟡 planned | — | `LEANPUB_API_KEY` |
| lulu | documented | 🟡 planned | — | `LULU_CLIENT_KEY`, `LULU_CLIENT_SECRET` |
| draft2digital | documented | 🟡 planned | — | `DRAFT2DIGITAL_API_TOKEN` |
| stripe | documented | 🟡 planned | — | `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY` |
| ingramspark | documented | 🟡 planned | — | `INGRAMSPARK_CLIENT_ID`, `INGRAMSPARK_CLIENT_SECRET` |

_Status legend: ✅ published (durable identifier recorded in `config.yaml`) · 🔵 reserved (identifier reserved but not yet registered by final publication) · ⚪ available (adapter implemented and locally verifiable) · 🟡 planned. This block is generated — edit `manuscript/config.yaml`, then regenerate with `uv run python -m infrastructure.publishing.status_report --project <path> --write`._
<!-- PUBLISHING-STATUS:END -->

This project is designed to run **inside** the [docxology/template](https://github.com/docxology/template) monorepo. All paths resolve relative to the repository root. The project reads public tracked exemplars from `fonds/templates/`, `tools/templates/`, and `rules/templates/` — these must be present.

```bash
# From the template repository root
uv sync
uv run pytest projects/templates/template_pools_rules_tools/tests/ -v
uv run python projects/templates/template_pools_rules_tools/scripts/02_run_integration.py
```

## Dependencies

- `pyyaml` — YAML manifest loading (always available in the template environment)
- `matplotlib` — deterministic PNG figure generation
- `jsonschema` — real validator-tool subprocess tests

## See Also

- `fonds/AGENTS.md` — fond discovery and validation conventions
- `rules/AGENTS.md` — rule loading and enforcement conventions
- `tools/AGENTS.md` — tool discovery and invocation conventions