# Project Knowledge Builder Output Contract

Use this reference when producing a full codebase knowledge base.

## Language Policy

Match the user's language for human-facing narrative docs. If the user writes in Chinese or asks for Chinese, write README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs in Chinese.

Keep technical anchors unchanged: source paths, commands, class names, method names, API paths, config keys, table names, permission codes, JSON keys and metadata enum values.

Generated indexes may remain technical and source-like. Do not hand-translate generated values if it reduces refreshability.

## Document Roles

| File | Purpose |
| --- | --- |
| `README.md` | Entry point, reading order, high-value links, freshness note. For Chinese output, title and usage guidance should be Chinese. |
| `CONTEXT.md` | Domain language, business capabilities, user roles, core nouns, invariants. |
| `CONTEXT-MAP.md` | Bounded contexts, module ownership, upstream/downstream dependencies, runtime boundaries. |
| `01-architecture.md` | System shape, module graph, request/data/control flows, extension seams. |
| `02-runtime.md` | Local run, build, env vars, Docker, deployment modes, process topology. Must identify local, Docker standalone and cloud modes when present. |
| `03-backend.md` | Backend modules, entrypoints, API conventions, service/mapper/entity patterns. |
| `04-frontend.md` | Frontend bootstrap, routing, state, API client, component/page conventions. |
| `05-data-and-migrations.md` | Databases, migrations, schema sources, seed data, table families. |
| `06-auth-permissions.md` | Authentication, authorization, token/session flow, permission-code lifecycle. Must explain menu/button permission flow when the repo has backend-driven menus. |
| `07-extension-guide.md` | How to add a feature end-to-end, with source-grounded examples. Must cover backend CRUD, frontend page and permission/menu data changes when applicable. |
| `08-troubleshooting.md` | Symptom-driven runbook with commands, files, and likely causes. |
| `09-rag-indexing.md` | Chunking, metadata, exclusions, refresh cadence, stale-data policy. |
| `adr/*.md` | Architecture decisions observed in the current code. |
| `generated/*.md` | Data-derived indexes that can be regenerated. |

## Required Sections

Each narrative doc should include:

- **Observed Sources:** concrete files or commands used.
- **Core Facts:** concise source-backed statements.
- **Operational Implications:** what developers must do differently because of those facts.
- **Unknowns/Risks:** gaps that need runtime access, DB export, product owner input, or external docs.

For Chinese output, use equivalent section labels:

- **已观察来源**
- **核心事实**
- **操作影响**
- **未知与风险**

## Newcomer Usefulness Gate

Before considering the knowledge base useful for handoff, verify that a new maintainer can answer:

1. What is the product/project, and which directories matter first?
2. How do I start or identify the active runtime mode?
3. Where are backend endpoints, frontend routes/pages, config, tables and permission codes indexed?
4. How do menu, button and backend permission checks connect?
5. When adding a normal feature, which backend, frontend, database and permission artifacts usually change?

If the answer is not obvious from README plus the narrative docs, add or revise human-facing guidance before finishing. Do not solve this by making generated indexes longer.

## Generated Indexes

### `project-inventory.md`

Include:

- repository roots
- build/package manifests
- primary languages
- major directories
- scripts
- Docker/compose files
- env files
- test files

### `backend-endpoints.md`

Include route method, path, class/file, approximate line, auth annotations, and notes. Do not invent full route paths when class-level and method-level mappings require Java expression resolution; show observed fragments and mark composition limitations.

### `frontend-routes.md`

Include static router files, dynamic route loaders, `src/views` index, route guard files, and external route package loaders.

### `config-reference.md`

Include env files, YAML/properties files, relevant keys, default values, and risk notes. Redact secrets.

### `database-dictionary.md`

Include SQL files, migration files, table names, table families, and whether the table is initialized, migrated, or inferred. Avoid loading huge SQL into prose; summarize and link.

### `permission-codes.md`

Include backend annotations, frontend permission helpers/usages, menu/permission SQL occurrences, and auth lifecycle notes.

## ADR Template

```markdown
# ADR NNNN: Title

Date: YYYY-MM-DD
Status: Observed

## Context

Source-backed facts that show the decision exists.

## Decision

The architecture decision embodied by the current code.

## Consequences

Benefits, tradeoffs, operational constraints, and migration risks.

## Sources

- `path/to/file`
```

## RAG Metadata

Recommended metadata per chunk:

```json
{
  "project": "name",
  "snapshot_date": "YYYY-MM-DD",
  "source_path": "path",
  "doc_type": "architecture|runtime|generated|adr|runbook",
  "domain": "backend|frontend|data|auth|deploy",
  "freshness": "manual|generated",
  "confidence": "observed|inferred|unknown"
}
```

## Anti-Patterns

- A long essay without generated indexes.
- “Best practice” advice unrelated to the repo.
- Copying README marketing text as architecture documentation.
- Claiming an endpoint, table, permission, or runtime mode exists without a source path.
- Hiding unknowns instead of listing them.