README.md was 481 lines, 60% of which was a nine-phase deployment runbook.
A new team member had to scroll past every deploy command to reach what
the folders are. The runbook moves out whole to spec/REBUILD.md - content
unchanged apart from heading levels and seven link targets repointed for
the new depth. README.md is now 258 lines.
Two additions:
"Start here" gives a reading order - README, then the workflow map, then
the current state, then CLAUDE.md - and a table routing to the runbook,
the build spec, the host brief or REQUESTS.md by what the reader came to
do. It also names the three accesses needed before starting, none of
which are in this repository.
The architecture diagram is redrawn because the old one was wrong. It
showed Authelia in front of ai-web. Since 28 August that hostname carries
no Authelia at all - it is matched on source IP. The README said so
correctly, 170 lines below the picture. The new diagram shows both
parties arriving at the same Caddy and then branching: ai.yokogawa.tech
to the @scada remote_ip matcher, the other three through import authelia.
The operator is inside the Caddy/Authelia environment; they take a branch
Authelia does not sit on. The answer path behind ai-api is drawn
separately, because it is the same whichever door the question came in
through. Structure follows caddy/ai-routes.caddy:190-203.
The layout block gains REBUILD.md and the eval count is corrected to 78
in passing, that line being part of the block rewritten here.
Every markdown link in all nine documentation files was checked after the
move: none broken.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The root held five documents of two different kinds with nothing to tell
them apart. This repo is being handed over as both design spec and
as-built record, so the two are now separated by lifetime:
spec/ BUILD-AI-CONTAINERS.md, YAU_Linux_Host_Onboarding.md
normative and durable - what we agreed to build
status/ workflow-map.html, current-state.html, REQUESTS.md
snapshots that go stale and get edited constantly
Nothing mechanical moved. The twelve code folders are deployment
interface - compose builds from /home/azureuser/ai/api, /web, /ingest and
deploy.sh copies from $HOME/ai/compose, /cube/model, /db - so they stay
where they are. CLAUDE.md stays at root because Claude Code loads it from
there, as do .gitignore and .gitattributes, which only apply repo-wide
from the root.
All 26 references to the build spec were bare filenames in prose, so the
move broke no mechanism. The seven markdown links in README.md and the
two pointers at the top of CLAUDE.md are repointed.
docs/ is deleted. It only ever held .gitkeep - nothing mounted or read
it, and ingest reads the host path /datadisk/ai-docs mounted at /docs
inside the container. An empty docs/ invites the misreading "project
documentation goes here". The ignore rule stays, now covering the whole
folder, so a controlled document dropped there still cannot be committed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
