cadline_web/www_archline_hu
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document the repo as a multi-site baseline generator (README + AGENTS.md) #3

Merged
imre merged 1 commits from docs/readme-agents into main 2026-07-18 17:26:21 +02:00
Conversation 0 Commits 1 Files Changed 2 +242 -58
imre.agent commented 2026-07-17 12:53:03 +02:00
Owner
Copy Link

Why

The repo now carries more than one site — main holds www.archline.hu, site/archlinexp.eu holds the eu site — and both are driven by the same site-agnostic generator. README.md still described a single-site repo, and there was nothing telling an automated agent the rules it must not break.

README.md (for humans)

Rewritten around the actual model:

  • One branch per site, not one repo per site; build-baseline.sh is site-agnostic (a new site = new branch with different content, not a modified script).
  • The baseline's dual role: known-good reference for the HIDS diff and the deployment source of truth — so code reaches production through git instead of direct live editing, and cleanup becomes a by-product of deploy.
  • Verify before you trust it, with the concrete reasons: the first archline candidate carried 34 malware files; on the eu site the checks caught a file-write webshell and an Akeeba restoration leftover holding a password — neither flagged by YARA.
  • Why a customized core file must never come from live: the updater skips customized files, so live silently keeps a stale base (the eu site reported 3.9.2 while its com_users was still pre-3.8.13 — 31 stale files). Take vanilla for the target version, apply only the genuine delta into overrides/.
  • Per-branch sections for both sites, and an explicit authority order (upstream package > developer source > live, and live only for reproduction fidelity / no-upstream extensions, vetted).

AGENTS.md (for machines) — new

The rules an agent must follow, in machine-facing form:

  • The cardinal rule: never build a baseline from an infected tree — core from upstream, own code from the developer source, live only for extensions with no obtainable upstream, and then vetted.
  • Mandatory post-build checklist: YARA (zero hits), IOC paths, disguise sweep, the structural core-namespace rule (an extra file on a core-component path that is not a template override is not a module — it is a leftover or a plant), and a core-version assertion. A contaminated baseline is never shipped; fix the constituents, don't filter the symptom.
  • Repository boundary: this is the customer's Gitea — no operator infrastructure may be referenced here, in files, commit messages or branch names.
  • Commit rules (English, Conventional Commits, never push to main, never commit a secret — cite file:line and type instead) and layer semantics (overrides/ wins, and why customized core files don't come from live).

Verification

  • Both files checked for cross-server references: none present.
  • Scope: 2 files, documentation only — no constituent, no generator, no build behaviour touched.
## Why The repo now carries more than one site — `main` holds www.archline.hu, `site/archlinexp.eu` holds the eu site — and both are driven by the **same site-agnostic generator**. `README.md` still described a single-site repo, and there was nothing telling an automated agent the rules it must not break. ## README.md (for humans) Rewritten around the actual model: - **One branch per site**, not one repo per site; `build-baseline.sh` is site-agnostic (a new site = new branch with different content, not a modified script). - The baseline's **dual role**: known-good reference for the HIDS diff **and** the deployment source of truth — so code reaches production through git instead of direct live editing, and cleanup becomes a by-product of deploy. - **Verify before you trust it**, with the concrete reasons: the first archline candidate carried 34 malware files; on the eu site the checks caught a file-write webshell and an Akeeba restoration leftover holding a password — neither flagged by YARA. - **Why a customized core file must never come from live**: the updater skips customized files, so live silently keeps a stale base (the eu site reported 3.9.2 while its `com_users` was still pre-3.8.13 — 31 stale files). Take vanilla for the target version, apply only the genuine delta into `overrides/`. - Per-branch sections for both sites, and an explicit authority order (upstream package > developer source > live, and live only for reproduction fidelity / no-upstream extensions, vetted). ## AGENTS.md (for machines) — new The rules an agent must follow, in machine-facing form: - **The cardinal rule**: never build a baseline from an infected tree — core from upstream, own code from the developer source, live only for extensions with no obtainable upstream, and then vetted. - **Mandatory post-build checklist**: YARA (zero hits), IOC paths, disguise sweep, **the structural core-namespace rule** (an extra file on a core-component path that is not a template override is not a module — it is a leftover or a plant), and a core-version assertion. A contaminated baseline is never shipped; fix the constituents, don't filter the symptom. - **Repository boundary**: this is the customer's Gitea — no operator infrastructure may be referenced here, in files, commit messages or branch names. - Commit rules (English, Conventional Commits, never push to `main`, never commit a secret — cite `file:line` and type instead) and layer semantics (`overrides/` wins, and why customized core files don't come from live). ## Verification - Both files checked for cross-server references: none present. - Scope: 2 files, documentation only — no constituent, no generator, no build behaviour touched.
imre.agent added 1 commit 2026-07-17 12:53:04 +02:00 
The repo now carries more than one site: main holds www.archline.hu and
site/archlinexp.eu holds the eu site, both driven by the same
site-agnostic generator. README.md still described a single-site repo.

Rewrite README.md around the actual model: one branch per site, the
baseline's dual role (known-good reference for the HIDS diff AND the
deployment source of truth), the verify-before-you-trust rule, and why a
customized core file must never be taken from live (the updater skips
customized files, so live silently keeps a stale base -- the eu site ran
a 3.9.2 version string over pre-3.8.13 com_users code).

Add AGENTS.md for automated agents: the cardinal never-build-from-an-
infected-tree rule, the mandatory post-build checklist (YARA, IOC paths,
disguise sweep, the structural core-namespace rule that caught what YARA
missed, core version assertion), the repository boundary, commit rules
and layer semantics.

Assisted-by: claude-code@claude-opus-4-8
imre merged commit 9fef8645a5 into main 2026-07-18 17:26:21 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: cadline_web/www_archline_hu#3
No description provided.
Delete Branch "docs/readme-agents"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?