<!-- 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:

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 and prefix* over stems; no field terms (title:x is a plain word — use --title, --section, --tag, --glob). A zero-result query carries suggestions; hyalo terms [PREFIX] lists the stemmed dictionary. "a b"~N allows N extra words between phrase tokens. Accents fold, identifiers match by whole or parts, and title/headings/tags outweigh body. --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; re-running create-index reuses unchanged files (--force rebuilds), and an --index read repairs drift in memory only. 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.