kb

Documentation

Overview

Package kb is shared infrastructure for ox's knowledge-base git repos: the per-project ledger and team-context clones. They have the same shape — a managed git working tree the daemon pulls and the CLI pushes to — and the same multi-writer hazards: server-side seed, CLI-side seed, several coworkers committing in parallel.

Anything that's true for both repo types belongs here. Things that are only true for one of them stay in their own package (internal/ledger/* for ledger-specific paths and lifecycle; the team-context layer in cmd/ox + internal/teamdocs for TC-specific behavior).

Index

• Variables
• func EnsureMergeAttributes(repoPath string) (changed bool, err error)

Variables

var MergeUnionPaths = []string{
	"AGENTS.md",
	"CLAUDE.md",
	"README.md",
	"CONVENTIONS.md",
	"SOUL.md",
	".gitignore",
}

MergeUnionPaths lists the root metadata files where multiple writers (server-side seed, CLI seed, coworker edits, doctor) routinely touch the same file concurrently in BOTH ledger and team-context repos. Declaring merge=union for these tells git to concatenate both sides on conflict instead of halting the rebase, which turns "wedged repo after first push" into "repo keeps moving; duplicate lines can be deduped later by a doctor pass."

merge=union is the same driver git uses for changelogs and NEWS files. It is safe for append-mostly metadata. It is NOT applied to session, history, murmur, or memory entry paths — those are conflict-free by construction since each entry has a unique timestamp- or id-based path.

Files included:

• AGENTS.md, CLAUDE.md, README.md, CONVENTIONS.md — appear at the root of both repo types; touched by humans, AI coworkers, server seed, ox prime injection.
• SOUL.md — team-context "soul" doc; multi-coworker writes are the point of the file.
• .gitignore — both repo types may have ignore patterns added by either side.

Exported so external tooling and tests can introspect the canonical list without re-deriving it.

Functions

func EnsureMergeAttributes

func EnsureMergeAttributes(repoPath string) (changed bool, err error)

EnsureMergeAttributes writes or updates the ox-managed merge-driver block in the KB repo's per-clone attributes file (.git/info/attributes). Idempotent. Preserves any content outside the managed block. Returns true if the file changed, false if it was already up to date.

The repo must already be a git working tree (have a .git directory). Caller passes the working-tree root, not the .git directory.

Designed to be safe to call on every pull/push cycle: idempotent, atomic write (temp + rename), best-effort error handling.