# 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.

```sh
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](https://tsok.org/knowledge/docs/deployment/) 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](https://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.
