hyalo git:20261003.e524babA

Immutable. This exact content never changes and is served at /api/v1/blob/b30390cfe82245cb.

---
name: hyalo
description: "Search and edit structured markdown knowledgebases with the Hyalo CLI: frontmatter, tags, tasks, links, and document structure."
---

<!-- hyalo:managed -->

# Hyalo knowledgebase workflow

Use the installed `hyalo` executable. In a Hyalo source checkout, `target/release/hyalo`
is an alternative when present. If unavailable, report that and suggest the project's
documented installation (`cargo install hyalo-cli`); do not install software as a
side effect of a knowledgebase query. On supported Node.js platforms, the published
npm route is `npm install --global @ractive-ch/hyalo`.

Run from the project root containing `.hyalo.toml`, then use `hyalo config --format json`
to locate and confirm the vault. Commands also work inside that configured vault,
including its nested folders. Other project subdirectories (for example `src/`
beside a `notes/` vault) do not inherit the vault configuration: return to the
project root before querying or editing. Do not assume the vault is named
`hyalo-knowledgebase` and do not repeat `--dir` when configuration already selects it.
File arguments are relative to the vault, including when launched from a nested folder.

Use `hyalo summary --format text` for orientation. Then select the smallest query
that answers the request:

```sh
hyalo find "release blockers" --format text
hyalo find --property status=planned --tag iteration --format text
hyalo read iterations/example.md --section Tasks --format text
hyalo backlinks iterations/example.md --format text
hyalo set iterations/example.md --property status=in-progress
hyalo task toggle iterations/example.md --line 12
hyalo lint iterations/example.md --format text
```

The paths above are examples: resolve actual files before running mutations.
Use `hyalo <command> --help` for exact syntax, advanced filters, links, or bulk operations.

For link validation, `HYALO006` checks targets and `HYALO008` checks heading anchors.
Both default to warnings and are promoted by `lint --strict` unless explicitly configured.
`links fix --dry-run` previews unique numbered-heading fragment repairs with source lines
and deferral reasons. Ordinary `links fix --apply` writes safe target and anchor repairs
together. `--apply-fuzzy` additionally enables eligible fuzzy file-target repairs; broader
fuzzy anchor guesses remain advisory. Broken counts describe the pre-apply scan.
Explicit hidden paths can resolve by existence without joining document discovery.

`find`'s positional query is ranked search; `-e` is regex. Quote filter expressions
and paths as single arguments using the active shell's quoting rules.

Ranked results include `score` and up to three body `matches` with `line`, `section`,
and `text`. Snippets rank by distinct query tokens then line number, share BM25
stemming/OR/CJK rules, and honor `--section`. Quoted phrases must fit on one line;
frontmatter is excluded and title-only hits can have an empty array. Indexed queries
read snippet text only for final results after `--limit`.
The query language: implicit AND, `OR` binding tighter (`a b OR c` = a AND (b OR c)),
`( … )` groups, `-` negation, `prefix*` over stems, and `title:`/`heading:`/`tag:`/`path:`
field terms (field-only queries score 0, no snippets). A zero-result query carries
`suggestions`; `hyalo terms [PREFIX]` lists the stemmed dictionary.
`--granularity section` ranks sections instead of files (`hyalo find 'query' --granularity
section --limit 5`, then follow the read hint); `--facet tags|property:K|type|dir` adds
`facets` file counts over the full match set (`hyalo find --tag X --facet property:status
--facet dir`).

Pass `--format text` for compact reading or `--format json` for structured output.
JSON is an envelope; results live in `.results`. `--jq` operates on that envelope
and cannot be combined with text format. Respect reported truncation; narrow the query
or increase `--limit` only when needed. Read diagnostics and exit status before treating
an empty result as success. Hints marked as writes require the same scope as any mutation.

User jq compilation and evaluation each run in a child with a 3-second deadline;
source/input/output limits are 64 KiB / 64 MiB / 10 MiB (at most 1,000,000 values).
Compilation failure precedes writes; evaluation failure retains committed effects.
Linux caps worker address space at 512 MiB. macOS/Windows have no hard memory cap;
intermediate allocations can still exhaust host memory before termination.

Prefer Hyalo for structured metadata changes and task toggles. Use normal editing
tools for body prose and new document bodies; preserve frontmatter and wikilinks.
Lint the changed files before handoff. This is an instruction, not an automatic hook.

For an audit, inspect and report. When repairs are requested, apply only those in scope.
Preview bulk or link repairs with the command's dry-run mechanism before applying them.
Avoid snapshot indexing for a small one-off query. For repeated work on a large vault,
`create-index` and `--index` help; rebuild after external edits and drop the index
when done. Never ignore an index staleness warning.

Profile skills describe OKF, MADR, Agent Skills, and changelog conventions. Use only
the profile relevant to the task and active configuration. Plugin and project installations
contain the same workflows; use one copy, and do not execute a task twice.