Skip to content

Documentation System

The root documentation site is the canonical handbook for repository and package behavior. It uses one landing page, section indexes, and stable topic pages so readers can move from orientation into checked-in proof without guesswork.

The goal is reader trust. The handbook should help a reviewer understand the design quickly, help a maintainer find the concrete anchors behind a claim, and stay explicit about what docs can explain versus what code, schemas, tests, and release assets must still prove.

These repository pages explain the cross-package frame that no single package can explain alone. They are strongest when they make the monorepo easier to understand without turning the root into a second owner of package-local behavior.

Visual Summary

flowchart TB
    page["Documentation System<br/>clarifies: see handbook layout | see honesty rule | understand reader promise"]
    classDef page fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a,stroke-width:2px;
    classDef positive fill:#dcfce7,stroke:#16a34a,color:#14532d;
    classDef caution fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    classDef anchor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95;
    classDef action fill:#fef3c7,stroke:#d97706,color:#7c2d12;
    detail1["root index"]
    detail1 --> page
    detail2["section indexes"]
    detail2 -.gives the reader orientation.-> page
    detail3["topic pages that carry proof"]
    detail3 --> page
    detail4["bijux-pollenomics"]
    detail4 -.gives the reader orientation.-> page
    detail5["bijux-masterclass"]
    detail5 --> page
    detail6["shared Bijux docs language"]
    detail6 -.gives the reader orientation.-> page
    detail7["self-sufficient docs"]
    detail7 --> page
    detail8["less meeting debt"]
    detail8 -.gives the reader orientation.-> page
    detail9["diagrams and prose that actually orient readers"]
    detail9 --> page
    next1["owning package docs"]
    page --> next1
    next2["schemas"]
    page --> next2
    next3["maintainer docs"]
    page --> next3
    class page page;
    class detail1,detail2,detail3,detail4,detail5,detail6,detail7,detail8,detail9 anchor;
    class next1,next2,next3 action;

Handbook Shape

  • one landing page that explains the split and routes readers quickly
  • one repository handbook for cross-package rules and shared assets
  • one five-category handbook per canonical product package
  • one maintainer handbook for repository-health automation
  • one compatibility handbook for legacy names and migration pressure

Documentation Rules

  • use stable filenames that describe durable intent
  • keep package handbooks on the same five-category spine
  • separate product docs, maintainer docs, and legacy-compat docs
  • update docs in the same change series that changes the underlying behavior

Concrete Anchors

  • pyproject.toml for workspace metadata and commit conventions
  • Makefile and makes/ for root automation
  • apis/ and .github/workflows/ for schema and validation review

Use This Page When

  • you are dealing with repository-wide seams rather than one package alone
  • you need shared workflow, schema, or governance context before changing code
  • you want the monorepo view that sits above the package handbooks

Decision Rule

Use Documentation System to decide whether the current question is genuinely repository-wide or whether it belongs back in one package handbook. If the answer depends mostly on one package's local behavior, this page should redirect instead of absorbing detail that the package should own.

What This Page Answers

  • which repository-level decision this page clarifies
  • which shared assets or workflows a reviewer should inspect
  • how the repository boundary differs from package-local ownership

Reviewer Lens

  • compare the page claims with the real root files, workflows, or schema assets
  • check that repository guidance still stops where package ownership begins
  • confirm that any repository rule described here is still enforceable in code or automation

Honesty Boundary

These pages explain repository-level intent and shared rules, but they do not override package-local ownership. They also do not count as proof by themselves; the real backstops are the referenced files, workflows, schemas, and checks.

Next Checks

  • move to the owning package docs when the question stops being repository-wide
  • check root files, schemas, or workflows named here before trusting prose alone
  • use maintainer docs next if the root issue is really about automation or drift tooling

Purpose

Use this page to understand how the handbook is organized, which section should own a question, and where repository guidance should stop.

Stability

Keep this page aligned with the actual docs tree and the layout rules enforced by this documentation catalog.