# TiDB Labs Knowledge Base Index

`AGENTS.md` is the directory for the repository knowledge base, not the
knowledge base itself. Long-form context belongs in
[`ARCHITECTURE.md`](./ARCHITECTURE.md) and the structured docs under
[`docs/index.md`](./docs/index.md).

## Start Here

- [`ARCHITECTURE.md`](./ARCHITECTURE.md): system context, runtime topology, and
  the key request paths.
- [`docs/index.md`](./docs/index.md): knowledge-base home and navigation across
  the docs tree.
- [`docs/FRONTEND.md`](./docs/FRONTEND.md): frontend stack, local dev modes,
  and validation.
- [`docs/PRODUCT_SENSE.md`](./docs/PRODUCT_SENSE.md): product framing, user
  journeys, and the main outcomes the codebase supports.
- [`docs/RELIABILITY.md`](./docs/RELIABILITY.md): runtime dependencies,
  orchestration caveats, CI, and deployment notes.
- [`docs/SECURITY.md`](./docs/SECURITY.md): auth, secrets, token flows, and
  review checkpoints.
- [`docs/PLANS.md`](./docs/PLANS.md): execution-plan layout and long-lived tech
  debt tracking.

## Knowledge Base Map

- [`docs/DESIGN.md`](./docs/DESIGN.md): how to use the design docs layer.
- [`docs/design-docs/index.md`](./docs/design-docs/index.md): catalog of design
  docs and design principles.
- [`docs/design-docs/core-beliefs.md`](./docs/design-docs/core-beliefs.md):
  documentation and architecture beliefs for this repo.
- [`docs/product-specs/index.md`](./docs/product-specs/index.md): catalog of
  product specs.
- [`docs/product-specs/new-user-onboarding.md`](./docs/product-specs/new-user-onboarding.md):
  current onboarding and lab-start journey.
- [`docs/exec-plans/active/README.md`](./docs/exec-plans/active/README.md):
  working area for active multi-step plans.
- [`docs/exec-plans/completed/README.md`](./docs/exec-plans/completed/README.md):
  archive for completed plans.
- [`docs/exec-plans/tech-debt-tracker.md`](./docs/exec-plans/tech-debt-tracker.md):
  cross-cutting debt that should stay visible between tickets.
- [`docs/generated/db-schema.md`](./docs/generated/db-schema.md): reserved path
  for generated or semi-generated schema inventory.
- [`docs/references/index.md`](./docs/references/index.md): short
  LLM-friendly reference notes for tools and conventions that affect day-to-day
  work.

## Repo Areas

- `frontend/`: Next.js 16 + React 19 user-facing site.
- `backend/`: Django 6 + DRF + Celery API and async orchestration.
- `ssh-proxy/`: Go WebSocket-to-SSH bridge. This subtree has its own
  [`ssh-proxy/AGENTS.md`](./ssh-proxy/AGENTS.md).
- `deployment/`: Ansible playbooks, compose templates, and production ops.
- `misc/`: diagrams, templates, and supporting assets.

## Maintenance Rules

- Keep this file short. If content starts becoming operational, architectural,
  or product-heavy, move it into `docs/` or `ARCHITECTURE.md`.
- Update the matching knowledge-base page in the same change when behavior,
  topology, or workflows change.
- Prefer one topic per document and link between docs rather than repeating the
  same explanation in multiple places.
- Put generated artifacts under `docs/generated/`. Put editorial docs under
  `docs/design-docs/`, `docs/product-specs/`, or `docs/exec-plans/`.
- Module-local `AGENTS.md` files override this index for their subtree.