# Mechanical Transmission Knowledge Base

This directory is the detached, read-only knowledge source for future
knowledge-assisted generation. It does not participate in the current CLI,
solver, CAD, validation, or joint-module execution paths.

## Safety boundary

- `knowledge_enabled` is conceptually `false` until an explicit integration
  layer is added later.
- Existing code under `src/` must not import this directory.
- Knowledge entries describe facts and bind stable capability IDs to existing
  implementations; they do not execute Python code.
- A mechanism is not considered supported merely because it has a topology
  entry. Its `maturity` and capability bindings define how far it can run.
- Generated experiments must eventually use `output/experiments/`, never the
  existing `output/runs/` production path.

## Layers

```text
schemas/       machine-readable contracts for every entry kind
ontology/      common vocabulary: ports, relations, units, maturity
components/    reusable parts and virtual references
relations/     local physical and kinematic connections
mechanisms/    executable mechanism units/topologies
compositions/  legal ways to connect mechanism units
capabilities/  bindings to solvers, layouts, CAD, and validators
evidence/      regression baselines and validation provenance
tools/         read-only consistency checks
```

The initial catalog only records capabilities already present in the project:

- `simple_2k_h`
- `simple_2k_h_cascade`
- `ferguson_wolfrom`
- the six currently registered topology relations

No new transmission structure is claimed to be executable in this first
version.

## Validate

From `backend/`:

```bash
python3 knowledge/tools/validate_knowledge.py
```

The validator uses the Python standard library. It checks entry identity,
cross-references, mechanism graph integrity, capability source locations, and
the hashes of the three legacy topology templates.