wayfinder_cli 0.2.0

Local OKF validation, knowledge indexing and semantic search.

Unreleased

• BREAKING: MCP search and default CLI text wayfinder search now return structured Markdown (## Matches and ## Related Context) with <path>:<lineStart>-<lineEnd> citations, single-line concept metadata, and resolved sources entries instead of the JSON search payload. Callers that require machine-readable JSON must use wayfinder search --output=json or remain on 0.2.0.
• Fix wayfinder mcp command dispatch to use the server's persistent retrieval service instead of the one-shot CLI default. Preserve explicit Dart knowledge factory overrides and ordinary one-shot command behavior.
• Reuse parsed snapshots across bundles in persistent MCP services when each canonical index directory, generation, and reread complete JSON text are unchanged. Cap retained JSON at 64 MiB UTF-8 with LRU eviction; larger records bypass the cache. Preserve source freshness, per-call store closure, exact search output, and one-shot CLI behavior. Failures, missing records, and disconnect clear the entry.
• BREAKING: Search is dense-only. Remove CLI --mode (including dense) and MCP mode. Retired inputs are rejected explicitly; unsupported MCP fields are not silently discarded. Every actual search requires the verified local encoder and compatible vectors; there is no model-free fallback. Existing compatible saved indexes need no rebuild solely for this cutoff. Model/input identity, snapshot format, context behavior, and bundle/Profile rules are unchanged.
• Reuse a lazy encoder across serialized MCP retrieval calls. Preserve source freshness and per-bundle locks; evict on failure and dispose on disconnect.

0.2.0

• wayfinder mcp without a bundle now discovers all configured project bundles, matching CLI project search/index. Search ranks them together with one query embedding, a global limit, and bundle-aware citations; index refreshes them all. Validate and graph return independent reports under bundles, with each validation report keeping its own gate and exit_code. No implicit indexing or partial search results are introduced. Explicit mcp <bundle> launches retain their result shapes; WAYFINDER_KNOWLEDGE_DIR remains an explicit single-bundle override. The plugin and new setup entries default to project mode. Existing entries need wayfinder setup --force and a host restart; unset the environment override for project-wide search. Bundles and Profile package formats are unchanged.
• Requires ack ^1.7.0 and wayfinder and wayfinder_embeddings ^0.2.0.
• The wayfinder and okfp Homebrew formulas are removed from btwld/homebrew-tap. wayfinder update tells a Homebrew installation the formula was removed and to reinstall with the install script.
• setup --session-hooks adds project-local, context-only startup hooks for Claude, Codex, and Gemini and an AGENTS.md pointer for Grok. The short bootstrap prompts loading use-wayfinder and its related skills; it performs no indexing or network requests. Existing hooks and instructions are preserved.
• search "<query>" searches all project bundle paths from wayfinder.json; --bundle <folder-name> optionally filters one. Matches rank across bundles with one query embedding and a global limit, preserving bundle-aware citations. index without a path refreshes the same bundle set. Explicit paths retain their existing behavior and JSON; missing/stale selected indexes still fail search without implicit indexing or partial results.
• wayfinder get and upgrade install the skill of every locked package that names one in skill, from its locked commit, into the project's .claude/skills/<id>/ and .agents/skills/<id>/ with a .wayfinder-profile marker, keeping each file's executable bit outside Windows. They never replace or remove a directory without the marker and fail before writing the lock when one is in the way. They remove a marked directory whose Profile no longer ships a skill or is no longer locked, and rewrite nothing when every marker is current. A skill root that a symbolic link at the root or an ancestor places outside the project is never pruned, and it fails get before the lock is written when a locked Profile ships a skill to install there; the message names every such root. Text output lists each skill; --output json adds skills and removed_skills. validate reports a missing or outdated copy as the wayfinder/profile-skill-stale warning without changing the gate.
• A project names only the Profile it applies; the package names its parent. wayfinder get follows each package's extends, reading a same-revision parent from the child's commit, composes every chain before it writes the lock, and locks a flat packages map with one source per Profile id, its git, ref, and path, resolved to one commit. Two chains that describe one id with different sources fail get naming both sources, even when they resolve to the same commit. Run twice with nothing changed, get fetches nothing and leaves the lock's bytes alone. A lock in the old profiles shape is rewritten. get --output json reports packages instead of profiles and drops direct. Validation selects through the resolver's select, which never fetches and reports each failure as one diagnostic, including a lock whose chain, release or parent disagrees with the cached package, or whose selected package records another git, ref or path than the configuration.
• wayfinder get reads each configured source's wayfinder-profile.json as a format 2 package and composes the chain before writing the lock, so a package this engine cannot read, or a chain that does not compose, fails get with the reason and leaves the lock untouched. A wayfinder.json key is the package id, in kebab-case, and the package must declare that id. Bitwild is bitwild-profile at profiles/bitwild; no chain has to reach it. The runtime archive no longer ships profile/.
• wayfinder validate and MCP validation of a 2026.2 bundle, or any bundle with no wayfinder.json above it, report wayfinder/config-missing with the Profile NOT ASSESSED and gate INCOMPLETE, exiting 2. An in-bundle profile.md no longer selects a Profile. Stay on wayfinder 0.1.x to keep validating a 2026.2 bundle unchanged, or migrate it to a wayfinder.json binding. The runtime archive no longer ships the 2026.2 Profile snapshot. The worked example moved to examples/bitwild, a wayfinder.json project whose bundle is examples/bitwild/knowledge; run wayfinder get examples/bitwild before validating it.
• wayfinder validate and MCP validation end with one derived gate, PASS, FAIL or INCOMPLETE, exiting 0, 1 or 2, and list the engine's wayfinder/* diagnostics beside the findings. A run that could not assess everything, such as an unresolved Profile source or a link graph that cannot be built, is INCOMPLETE and never PASS. JSON drops judgment_rules and automated_gate. With --output json or sarif, a run that stops still prints a result carrying wayfinder/internal-error.
• wayfinder get decodes the Profile manifest and rule catalog that git show prints as UTF-8, so a non-ASCII character such as § no longer comes back as § on Windows.
• wayfinder validate and MCP validation report what Profile 2026.3 permits, such as an unresolved planned link, as summary entries: JSON profile.summary, a text Summary: block, and SARIF informational results. They never change the gate or the exit code. The resolver rejects a composed binding that declares a tag equal to a type, status, trust tier, or relationship name.
• wayfinder graph and the MCP graph tool add each concept's typed relationships frontmatter entries beside okf's graph. JSON keeps every okf key and adds a field_edges array; Mermaid and DOT label each added edge with its relationship name, quoted in Mermaid so a name containing | still parses. Search expansion follows the same relationships, before untyped body links, and a context hit reached through one carries its relationship name. Saved indexes stay compatible.
• Project bindings accept relationships, declared like tags, and the resolver composes them through extends with the same collision checks.
• wayfinder validate --fix writes okf's generated indexes for a Profile 2026.3 bundle, then validates. It writes only index files that differ, never writes a 2026.2 bundle or one that fails OKF, and says which applied.
• wayfinder validate and MCP validation recognize configured Bitwild Profile 2026.3 bundles; CLI validation accepts --config for an explicit project file. Both validate read-only from a current lock/cache; get and upgrade are the explicit fetching and lock-writing commands. Graph, index, and search do not resolve unused Profile sources. Legacy 2026.2 bundles remain supported.
• index --detach runs one background index per machine; while one runs, it reports that and starts nothing. A background index stops after 30 minutes or once its bundle directory is removed. The git hooks from setup --hooks skip file checkouts, new clones and worktrees, and changes that leave the bundle alone; rerun wayfinder setup --hooks to update existing hooks.
• setup --hooks no longer adds Claude Code and Codex Stop hooks, which indexed after every agent turn in every workspace. Rerunning it removes the Stop hooks earlier releases added and keeps every other hook; search still reports a stale index, and the MCP index tool refreshes it.

0.1.2

• Refresh the plugin and authoring skills so they copy OKF §5 inline frontmatter and refuse a silent Profile release change.
• An unsupported Profile release is reported as NEEDS HUMAN, not a 2026.2 judgment failure. Graph CLI filters match the MCP graph tools.

After upgrading, run wayfinder update so the plugin and skills refresh. Existing 2026.2 bundles stay conformant. Profile validation, the embedding model, the ObjectBox schema, and index configuration are unchanged.

0.1.1

• Recover oversized separators and identifiers without aborting bundle indexing or editing source files, using wayfinder_embeddings 0.2.0.
• Report oversized-input recoveries as structured warnings in completed/current CLI JSON and MCP index results, and escaped stderr warnings in text mode.
• Replay persisted warnings without loading the model, including foreground calls after detached completion; detached status acknowledgements are unchanged.
• Bump application index configuration to 3 for lossless splitting and conditional context omission. Existing indexes require one rebuild; source bundles need no edits.
• Harden the public installers' platform and input validation before network access, including an explicit error for unknown Windows architectures.

After upgrading, run wayfinder index <bundle> once before searching. JSON consumers must allow the additive warnings field. Profile validation, the embedding model, and the ObjectBox schema are unchanged.

0.1.0

• Report Profile 2026.2 and depend on okf ^0.5.0. wayfinder validate prints Profile 2026.2 and treats a bundle declaring 2026.1 as an unsupported release. Date-only timestamps surface as okf's non-blocking okf/timestamp-without-offset advisory and leave the gate passing.

0.0.4

• wayfinder graph <bundle> prints the bundle's OKF relationship graph as JSON, Mermaid or DOT, filtered by type, path prefix or link resolution. MCP clients get a read-only graph tool.
• Native installs also report sources paths that resolve to nothing as validation advisories, and no longer treat adjacent footnote references ([^a][^b]) as a missing-source error. The pub.dev package gains both with the next wayfinder core release.

0.0.3

• Homebrew installations are directed to the install script because the formula is no longer updated.

• wayfinder index returns without loading the model when the saved index already matches the bundle, and reports current in JSON output.

• index --force discards the saved index and re-embeds every passage.

• index --detach returns at once and indexes in the background only when the bundle changed.

• wayfinder setup --hooks refreshes the index after Claude Code and Codex turns and after git pulls, checkouts and rebases.

0.0.2

• wayfinder skills install|status|remove installs the bundled agent skills for Claude Code, through the wayfinder plugin when the claude CLI is available, and for ~/.agents/skills readers such as Codex.
• wayfinder setup adds the Wayfinder MCP server to a project's .mcp.json.
• wayfinder update upgrades installer-managed runtimes and refreshes skills and the plugin. Interactive commands mention a newer release at most daily.
• Native bundles include the skill family.

0.0.1

Application moves from wayfinder to wayfinder_cli. The executable remains wayfinder, including MCP. Core validation comes from wayfinder; native installs no longer require okfp.

Changelog

0.0.1-dev.1

• Use the wayfinder_embeddings package for retrieval.
• Preserve saved indexes across the library rename; write compatible schema markers.
• Support WAYFINDER_EMBEDDING_MODEL while retaining the legacy override.
• Align package setup, native builds and documentation with Wayfinder naming.

0.0.1-dev.0

• Validates explicit local OKF bundles through the existing OKF Profile checks.
• Indexes and searches bundle passages using verified local embeddings and persistent ObjectBox storage, preserving original citations.
• Reuses compatible vectors and rejects stale or incompatible indexes.
• Serves validation, indexing, and search over MCP stdio.
• Keeps contextual Profile judgment explicitly unassessed by automated checks.

Indexing and search require separately prepared model weights and native libraries. The Dart package does not include the complete native runtime bundle.