Contributing¶

kata is a Go project with a local daemon, CLI, TUI, SQLite store, JSONL import/export path, and federation tests. Keep changes small, verified, and documented.

Repository layout¶

Path	Responsibility
`cmd/kata`	CLI commands and output modes.
`internal/daemon`	HTTP routes, daemon runtime, auth, SSE, federation routes.
`internal/db`	Storage contract, backend implementations, schemas, projections, events, queries, federation state.
`internal/embedding`	OpenAI-compatible embeddings client and text recipe (storage-free).
`internal/vector`	Backend-native semantic index: SQLite sidecar/sqlite-vec or canonical PostgreSQL/pgvector tables, plus mirror, generation lifecycle, fill, and query.
`internal/client`	Client discovery, auto-start, remote daemon, bearer handling.
`internal/tui`	Bubble Tea TUI.
`web`	Svelte browser source, generated API types, component tests, Playwright fixtures, and asset tooling.
`internal/jsonl`	Export/import, cutover, fixture compatibility.
`internal/federation`	Spoke-side federation client and runner.
`docs`	Public Zensical documentation source and maintained design notes.

Building¶

Release binaries are pure Go (CGO_ENABLED=0): modernc.org/sqlite provides both the database driver and the sqlite-vec extension. Development builds on machines with a C toolchain default to CGO_ENABLED=1, where kit's sqlitevec selects its cgo sqlite-vec bindings by build constraint; those need C sqlite symbols at link time, so internal/vector/driver_cgo.go links mattn/go-sqlite3 purely to keep ambient go build/go test working. Both driver shims live in internal/vector/driver_*.go — nothing to configure, but don't remove the mattn dependency because release builds don't use it.

Local checks¶

Run:

make test
make vet
make lint
make nilaway

Browser UI development¶

The web toolchain is pinned to Node 26.5.1 and Bun 1.3.14; use those exact versions so the frozen lockfile and generated output match CI.

Install the pinned web dependencies, then start the current Go checkout and Vite together:

make web-install
make web-dev

web-dev builds the repository binary without installing it and creates an owned temporary home, workspace, and database beneath the ignored .kata-web-dev/ directory. Vite serves http://127.0.0.1:5173 and proxies API and event-stream requests to that isolated daemon using the same configured origin, browser-session, CSRF, and SSE policy as production. It does not add a development authentication or Origin bypass. Set KATA_WEB_DEV_PORT to use a different Vite port.

Run the static, unit, and real proxy checks with:

make web-check web-test
make web-test-browser
make web-e2e

The browser check creates a real session inside its isolated run; it does not use an installed daemon or a developer database.

Before release packaging, run:

make web-build web-assets-check web-embed
make web-release-check

web-release-check builds a full Kata binary and refuses the harmless Go-only asset stub or an incomplete production graph. Published archives must all use the same validated embedded distribution.

Federation-specific checks:

make test-stress
make test-federation-docker

The pre-commit hook protects released PostgreSQL migration history. Install the configured hooks with prek install; see PostgreSQL migrations before proposing a schema change.

make test-stress runs randomized and failpoint tests. If Rapid prints a failing seed, reproduce it with the seed from the failure output:

RAPID_SEED=<seed> go test -tags federation_stress ./e2e \
  -run TestFederationStressRandomizedWorkload \
  -count=1 \
  -timeout 2m

Documentation checks¶

Install Zensical:

make docs-install

Build the site:

make docs-check

Preview locally:

make docs-serve

Zensical's preview server is for local preview only. Publish the generated static files from site/ with a real static host, CDN, or web server.

Documentation standards¶

Public docs should describe implemented behavior first. Technical notes under docs/design/ cover deeper design rationale, trade-offs, and low-level constraints; keep them current as decisions change rather than letting stale design drafts accumulate.

When changing behavior:

update CLI help when flags or contracts change;
update README.md if the project overview or quickstart changes;
update docs/ for public user/operator behavior;
record durable design rationale in docs/design/ when the "why" is not obvious from the code.

Commit discipline¶

Do not leave accepted repository changes uncommitted at the end of a task. Do not squash or amend history unless explicitly asked.

When closing kata issues, close with a substantive message and typed evidence:

kata close abc4 --done \
  --message "Updated docs for remote daemon auth and verified docs-check passes." \
  --commit <sha> \
  --test "make docs-check"

If work is incomplete, leave the issue open and add a comment explaining what was attempted and what remains.