Repository Handbook¶

Open the repository handbook when the question belongs to the part of bijux-canon that no single package owns alone: why the split exists, which rules belong at the root, and how package handoffs stay explicit across the repository.

The main repository mistake this handbook is meant to prevent is root creep. The root should coordinate package truth, not become a second product layer that quietly re-explains or overrides package ownership.

The root is a coordination layer, not a shadow owner. Product behavior belongs in the publishable packages under `packages/`. The root owns only what is genuinely shared: workspace layout, schema governance, documentation rules, validation posture, and release coordination.

Reader Contract¶

This handbook should answer three questions before a reviewer touches code:

is the concern genuinely repository-wide, or does one package own it
which shared file, schema, workflow, or rule backs the claim
where should the reader go next when the root no longer has authority

flowchart TD
    question["reader question"]
    root{"cross-package concern?"}
    package["owning package handbook"]
    maintain{"maintainer machinery?"}
    compat{"legacy name?"}
    foundation["foundation pages"]
    operations["operations pages"]
    devdocs["maintenance handbook"]
    compatdocs["compatibility handbook"]
    proof["root proof surfaces"]

    question --> root
    root -- no --> package
    root -- yes --> maintain
    maintain -- yes --> devdocs
    maintain -- no --> compat
    compat -- yes --> compatdocs
    compat -- no --> foundation
    compat -- no --> operations
    foundation --> proof
    operations --> proof

The repository handbook is strongest when it routes quickly and then stops. It should make the shared root logic legible, show where package authority begins, and point to the concrete files that back the claim instead of trying to re-explain package behavior from above.

Start Here¶

open Foundation for repository shape, split logic, ownership boundaries, and shared terminology
open Operations for contributor workflow, validation posture, release flow, and review rules
open the Maintenance Handbook when the concern is helper code, Make routing, workflow fan-out, or repository-health automation
open the Compatibility Handbook only when an older or shorter compatibility name, preserved import root, or migration question is still active
leave this handbook as soon as the behavior is clearly local to one canonical package

What This Handbook Owns¶

why the repository is split into canonical packages instead of one combined surface
root-owned workflow, validation, release, artifact, and documentation rules
the seams where one package hands authority to another package or to a shared root rule

What This Handbook Does Not Own¶

ingest, index, reason, agent, or runtime behavior inside the product handbooks
helper implementation detail that belongs in the maintainer handbook
compatibility-alias migration policy that belongs in the compatibility handbook

Shared Package Map¶

Canonical package	Repository-level promise	Root-level proof to inspect
`bijux-canon-ingest`	source material becomes deterministic preparation output before downstream use	package entry in `pyproject.toml`, handbook route in `mkdocs.yml`, package code under `packages/bijux-canon-ingest`
`bijux-canon-index`	retrieval executes through auditable contracts rather than hidden search behavior	API schema under `apis/bijux-canon-index`, package tests, handbook route
`bijux-canon-reason`	retrieved evidence becomes claims, checks, and reasoning artifacts	API schema under `apis/bijux-canon-reason`, package tests, handbook route
`bijux-canon-agent`	role-based orchestration emits traces instead of swallowing decisions	API schema under `apis/bijux-canon-agent`, package tests, handbook route
`bijux-canon-runtime`	the full run is accepted, rejected, persisted, or replayed under explicit policy	API schema under `apis/bijux-canon-runtime`, runtime regression tests, handbook route

Boundary Example¶

A schema pin under apis/, a workspace-level validation rule, or a handbook routing rule belongs here because it protects more than one package at once. A change to ingest chunking, runtime replay semantics, or reason-level claim formation does not belong here, even if the root automation or docs also have to move with it.

First Proof Checks¶

check pyproject.toml when the claim is about workspace structure or commit rules
check Makefile, makes/, and .github/workflows/ when the claim is about shared automation or validation
check apis/ when the claim is about shared schema storage or compatibility review
check packages/ when the question is whether the root is starting to blur a package boundary

Cross-Package Anchors¶

pyproject.toml declares the workspace and package set
mkdocs.yml defines the published handbook structure
Makefile, makes/, and .github/workflows/ carry root-level operations
packages/ carries the canonical product boundaries the root must not blur

Leave This Handbook When¶

the behavior is already local to one package's interfaces, workflows, or tests
the question is really about maintainer automation internals
the real work is compatibility alias routing rather than a root-owned rule