layered-soul/skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md

# Graphify on FreeBSD / Clawdie ISO investigation

Use when considering Graphify (`graphifyy` / `graphify` CLI) for FreeBSD build hosts, live/operator USB images, or Clawdie-ISO package lists.

## Current assessment

Graphify is useful for Clawdie codebase navigation, but do **not** assume it runs cleanly on FreeBSD until a real FreeBSD smoke test passes. Prefer Linux/dev-host graph generation first.

## Known package facts checked

PyPI package:

```text
package: graphifyy
cli: graphify
license: MIT
python: >=3.10
```

PyPI provides source distributions, but no FreeBSD wheels were observed for `graphifyy` or key compiled deps. FreeBSD will likely build some dependencies from source unless FreeBSD packages cover them.

FreeBSD 15 amd64 quarterly packages observed available for the clean Python
3.12 baseline:

```text
python312
uv
```

Not observed as Python 3.12 FreeBSD packages in that check:

```text
graphifyy
Python package-flavored graph dependencies such as datasketch, numpy, scipy,
rapidfuzz, networkx, and tree-sitter grammar packages
```

## Integration rule

For FreeBSD/ISO projects, add Graphify docs/scripts first, but do **not** add it to runtime package lists or make image build/boot/publish depend on it until FreeBSD smoke tests pass.

## FreeBSD smoke test

Run on the target FreeBSD builder/host from a clean repo checkout:

```sh
mkdir -p tmp/graphify-test
export TMPDIR="$(pwd)/tmp/graphify-test"
pkg install -y python312 uv git cmake ninja
uvx --python 3.12 --from graphifyy graphify --help
```

Small extraction first:

```sh
uvx --from graphifyy graphify extract docs --out tmp/graphify-test/out --no-cluster
python3 -m json.tool tmp/graphify-test/out/graphify-out/graph.json >/dev/null
uvx --from graphifyy graphify query "what is this repository about?" --graph tmp/graphify-test/out/graphify-out/graph.json
```

Only after that passes, test the whole repo with a strict `.graphifyignore`:

```sh
uvx --from graphifyy graphify extract . --out tmp/graphify-test/full
python3 -m json.tool tmp/graphify-test/full/graphify-out/graph.json >/dev/null
```

## Clawdie-specific boundary

- Clawdie-AI/Clawdie-ISO repo scaffolding: OK now.
- Linux/dev-host generated graphs: OK now.
- FreeBSD host optional tool: only after smoke test.
- Clawdie live USB / ISO runtime dependency: not until offline/dependency behavior is proven.
- Graphify must never block image build, boot, webroot publishing, or Hermes USB/IMG deployment.