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`	`kata.vectors.db` sidecar: mirror, generation lifecycle, fill, KNN query (built on `go.kenn.io/kit/vector`).
`internal/client`	Client discovery, auto-start, remote daemon, bearer handling.
`internal/tui`	Bubble Tea TUI.
`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

Federation-specific checks:

make test-stress
make test-federation-docker

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.