# WD0-7 Knowledge Base Refactor

Status: implemented locally, not yet published

## Goal

Turn the root `AGENTS.md` into a concise knowledge-base directory card and move
durable repository context into a structured docs tree.

## Problems In The Previous State

- The root `AGENTS.md` had become a long catch-all onboarding document.
- Knowledge about architecture, product behavior, reliability, and security
  lived in one file instead of following stable repository seams.
- The repo did not have a durable `docs/` structure for future knowledge-base
  growth.

## Current Structure

- Root [`AGENTS.md`](../../../AGENTS.md): short index and maintenance rules
- Root [`ARCHITECTURE.md`](../../../ARCHITECTURE.md): runtime topology and key
  request paths
- Root [`README.md`](../../../README.md): entrypoints into the knowledge base
- Knowledge-base home: [`../../index.md`](../../index.md)
- Design docs: [`../../design-docs/index.md`](../../design-docs/index.md)
- Product specs: [`../../product-specs/index.md`](../../product-specs/index.md)
- Plans and debt: [`../../PLANS.md`](../../PLANS.md),
  [`../tech-debt-tracker.md`](../tech-debt-tracker.md)
- References: [`../../references/index.md`](../../references/index.md)
- Generated inventory: [`../../generated/db-schema.md`](../../generated/db-schema.md)

## Key Decisions

- Keep `AGENTS.md` intentionally short and treat it as a map, not the primary
  storage location for repo knowledge.
- Split durable knowledge by concern:
  architecture, design, product sense, reliability, security, plans,
  references, and generated artifacts.
- Seed each directory with at least one concrete document so the structure is
  usable immediately instead of being empty scaffolding.
- Add root entrypoints in `README.md` so the knowledge base is reachable from
  the repo front door, not only through agent-specific onboarding.

## Validation

- `git diff --check`
- Relative markdown-link validation across the knowledge-base files

## Publication Blocker

- The docs refactor is ready in the working tree but cannot be published from
  this environment because git metadata writes and GitHub access are blocked.

## Follow-Up Areas

- Deepen topic coverage as the repo evolves, especially design docs and product
  specs.
- Automate `docs/generated/db-schema.md` so it becomes a true generated schema
  artifact instead of a bootstrap inventory.