Build, preview, and release Knowledge

The Rust crate lives in apps/knowledge. Knowledge pages are part of apps/www. The repository root owns the Cargo and pnpm lockfiles. Run Nx commands from the repository root.

pnpm install --frozen-lockfile
pnpm nx build knowledge
pnpm nx test knowledge
pnpm nx build www
node apps/www/scripts/check-knowledge.mjs

The build and test targets use the HTTP model profile with SQLCipher, MCP, S3, and PostgreSQL. Use the platform build helper for native GGUF, multimodal, Metal, CUDA, or Vulkan. Add the selected build directory to PATH so the CLI runs as knowledge. The default workspace output directory is target.

Website

apps/www/src/app/knowledge uses the same Next.js layout, navigation, theme, and editorial components as the rest of tsok.org. apps/www/src/lib/knowledge-guides.ts enrolls the Markdown source files. The static export contains rendered guides, raw Markdown, llms.txt, llms-full.txt, sitemap.xml, the reference YAML, the OpenAPI schema, and SKILL.md. The existing Pages workflow publishes the site at tsok.org/knowledge.

Releases

Merge app changes into main using Conventional Commit titles with the knowledge scope. The release workflow reads commits that touch apps/knowledge since the last Knowledge release. fix, perf and revert increment the patch. feat increments the minor version. A breaking marker increments the major version. Documentation, chores and build commits can deploy site updates independently of binary releases.

The initial release uses the package's existing beta version. Subsequent releases build the calculated version for Linux x86-64 and ARM64, macOS Intel and Apple silicon, and Windows x86-64. The Apple silicon artifact enables Metal. The other artifacts use CPU inference. Archives contain the binary, sample OKF data, configuration, docs, and schemas. Model weights and external media decoders are separate installations.

After every matrix job succeeds, the workflow checks the artifacts and atomically pushes the version commit and its namespaced knowledge-v<semver> tag. It uploads the binaries and SHA256SUMS to a draft GitHub Release, publishes the release, and refreshes GitHub Pages. Existing releases for other apps keep their repository-wide latest designation. Download access follows the private repository's permissions.

Preview the next version locally with python3 apps/knowledge/scripts/release.py plan. If a run fails after tagging, rerun that same workflow run. It checks that the tag still points to the expected release commit before resuming.

Read Markdown →