Editing Openai/693c70a4-9498-8011-87ee-efb5576cc53d (section)

=== Assistant: That’s a very fair reaction — and you’re right to ask “how would I know this?” ===
That’s a very fair reaction — and you’re right to ask “how would I know this?”
So let me explain cleanly, from first principles, without assuming prior knowledge.

==== ### ====

You have two different roles inside one project:

|     |     |     |
| --- | --- | --- |
|     |     |     |
|     |     |     |

This is not arbitrary — it’s how modern CI/CD systems prevent confusion.

==== ### ====

Example:

<syntaxhighlight>src/index.html
src/en/index.html
src/zh/index.html
src/assets/…

</syntaxhighlight>

These are:
* human-readable
* editable
* version-controlled
* reviewed in GitHub

👉 This is the “authoring layer”

===== What it does: =====

<syntaxhighlight lang="text">src/  ──▶  (build step)  ──▶  site/

</syntaxhighlight>

Specifically:
* Tailwind compiles CSS
* build-meta.sh writes site/build-info.json
'' You copy src/'' → site/*

👉 Nothing serves from <code>src/</code>
👉 Browsers never see <code>src/</code>

===== Your VPS config proves this: =====

<syntaxhighlight lang="yaml">volumes:
* ./site:/usr/share/caddy

</syntaxhighlight>

So:

|     |     |
| --- | --- |
|     |     |
|     |     |
|     |     |

👉 Caddy does not know <code>src/</code> exists

==== Because site/ is temporary output. ====

If you edit:

<syntaxhighlight>site/index.html

</syntaxhighlight>

It will be overwritten next time you do:

<syntaxhighlight lang="bash">npm run build
cp -r src/* site/

</syntaxhighlight>

That’s why professionals say:

: 

==== The correct mental model should have been stated earlier like this: ====

: 

: 

: 

You weren’t wrong — this was implicit knowledge, not obvious.

==== This structure allows: ====
* CI to rebuild safely
* Deploys to be repeatable
* Rollbacks to work
* Multiple environments (LOCAL / CI / PROD)
* Auditable builds (which you explicitly want)

Without it, CI/CD becomes chaotic and unverifiable — exactly the pain you were feeling.

==== You did something very correct: ====

<syntaxhighlight>src/index.html
  └── fetch('/build-info.json')

</syntaxhighlight>

That means:
* Source defines how metadata is displayed
* Build defines what metadata is displayed
* Server just serves static files

This is clean separation of concerns.

==== : ====

You wouldn’t —
unless someone explicitly told you the source vs artifact rule.

Now you know it, and you’re actually applying it correctly.

If you want, next I can:
* Draw a one-page mental diagram (Local → Repo → VPS)
* Lock naming conventions so this never drifts again
* Convert this into a short internal “WSI Deployment Rulebook”

Just say which one.