Developer notes

This page is for maintainers. It explains documentation boundaries rather than training logic.

What specs/, root documents, and docs-site/ each do

specs/

This directory is the implementation authority. Rules, data formats, file layout, and training boundaries are defined there.

Root documents

The repository root holds project entry documents such as:

• the main README
• the operations guide
• the configuration reference
• the data directory note

Those files are already authoritative, so the docs site should reuse them through symlinks instead of copying them.

docs-site/

This directory explains the project:

• what it is
• why it is structured this way
• how inputs and outputs move through the system
• how readers can judge whether behavior looks normal

That means docs-site/ should help people understand the project without becoming a second source of truth.

Why DRY matters here

The biggest documentation failure is not storage cost. It is losing track of which copy is current.

For this repository, these should not be duplicated casually:

• main README content
• configuration reference
• operating steps
• docs-site PRDs

When a Markdown source already exists and is authoritative, prefer a symlink.

Which content should be written directly under docs-site/docs/

These pages need to be authored because they explain rather than define:

• home pages
• project overview
• training loop notes
• data and recovery notes
• developer notes

Why specs/ is not being translated in this round

The constraint here is explicit:

• specs/ stays unchanged
• specs/ remains Chinese in this task

So the docs site explains what specs/ is for, keeps English entry pages for the documentation structure, and avoids creating a second translated implementation rulebook.