---
name: docxology/infrastructure-tools
source: https://app.decimal.ai/s/docxology-infrastructure-tools@1/SKILL.md
source_sha256: 825c877d178b
---

# Tools Module

Discovery, validation, scope, and sidecar symlink sync for the `tools/`
workspace — executable entry points (scripts, skills, agents), distinct from
`projects/` (executable research code) and `fonds/` (passive data stores).

## Modules

| File | Exports |
|------|---------|
| `__init__.py` | `ToolInfo`, `build_tool_info`, `discover_tools`, `resolve_tool_root`, `validate_tool_structure` |
| `discovery.py` | `discover_tools`, `resolve_tool_root`, `NON_RENDERED_TOOL_SUBDIRS`, `RENDERED_TOOL_SUBDIRS` |
| `tools_info.py` | `ToolInfo`, `build_tool_info` |
| `validation.py` | `validate_tool_structure` |
| `public_scope.py` | `PUBLIC_TOOL_NAMES`, `public_tool_infos`, `public_tool_names` |
| `linking.py` | `sync_private_tool_links`, `sync_active_tool_links`, `private_tools_root`, `is_managed_symlink`, `LIFECYCLE_LINK_DIRS`, `LinkSyncResult` |

## Discovery and validation

```python
from pathlib import Path
from infrastructure.tools import discover_tools, resolve_tool_root, validate_tool_structure, ToolInfo

# Discover all valid tools (skips working/, archive/)
tools: list[ToolInfo] = discover_tools(Path("."))
for t in tools:
    print(t.qualified_name, t.tool_type, t.is_valid)

# Resolve by name
path = resolve_tool_root(Path("."), "templates/template_code_executor")
path = resolve_tool_root(Path("."), "template_code_executor")  # bare name

# Validate structure (requires tools.yaml + scripts/)
is_valid, message = validate_tool_structure(Path("tools/templates/template_code_executor"))
```

## ToolInfo dataclass

```python
from infrastructure.tools import ToolInfo, build_tool_info

info = build_tool_info(Path("tools/templates/template_code_executor"))
info.name           # "template_code_executor"
info.tool_type      # "type" from tools.yaml, or "generic"
info.has_scripts    # True iff scripts/ exists
info.is_valid       # True iff has_scripts
info.qualified_name # "template_code_executor" or "program/name"
```

## Public scope

```python
from infrastructure.tools.public_scope import (
    PUBLIC_TOOL_NAMES,   # ('templates/template_code_executor',)
    public_tool_infos,   # list[ToolInfo] present in checkout
    public_tool_names,   # list[str] sorted
)
```

## Sidecar sync

```python
from pathlib import Path
from infrastructure.tools.linking import (
    sync_private_tool_links, private_tools_root,
    is_managed_symlink, LinkSyncResult,
)

root = private_tools_root(Path("."))   # Path | None
result: LinkSyncResult = sync_private_tool_links(Path("."), dry_run=True)
print(result.summary())
# result.created / .updated / .removed / .skipped / .changed
```

## CLI

```bash
uv run python -m infrastructure.tools.linking --dry-run
uv run python -m infrastructure.tools.linking
uv run python -m infrastructure.tools.linking --no-prune
uv run python -m infrastructure.tools.linking --private-root /path/to/tools
```

## Tool structure contract

| Path | Required? |
|------|-----------|
| `tools.yaml` | ✅ manifest |
| `scripts/` | ✅ executable entry points |
| `tests/` | optional |
| `docs/` | optional |

## Discovery scope constants

```python
from infrastructure.tools.discovery import NON_RENDERED_TOOL_SUBDIRS, RENDERED_TOOL_SUBDIRS
# NON_RENDERED_TOOL_SUBDIRS = frozenset({"working", "archive"})
# RENDERED_TOOL_SUBDIRS = frozenset({"templates"})
```

## Environment variables

| Variable | Purpose |
|----------|---------|
| `TEMPLATE_TOOLS_ROOT` | Override private tools root (highest precedence) |
| `TEMPLATE_SKIP_TOOL_LINK_SYNC` | Set to skip auto-sync in orchestration CLI |

## Safety invariants (linking.py)

- Real directories and unmanaged symlinks are **never** touched.
- `PROTECTED_NAMES` (public exemplars from `PUBLIC_TOOL_NAMES`) are always skipped.
- No-op and no error when the private sidecar is absent.

## See also

- [`AGENTS.md`](AGENTS.md) — full operating contract, boundaries, lifecycle layout
- [`../fonds/SKILL.md`](../fonds/SKILL.md) — closest analog (fonds module skill)
- [`../project/SKILL.md`](../project/SKILL.md) — canonical project-layer skill (same pattern)