Merge pull request #56 from cemililik/development

docs: README rewrite, inclusive messaging, and v0.7.x housekeeping

Author: cemililik

.agents/skills/sync-bilingual-docs/SKILL.md

@@ -14,6 +14,7 @@ Any change to these paths or their siblings:
 - `docs/product_strategy.md` / `product_strategy-tr.md`
 - `docs/roadmap.md` / `roadmap-tr.md`
 - `docs/reference/*.md` (has matching `-tr.md`)
+- `docs/usermanuals/{en,tr}/**/*.md` (the static-site SPA viewer source)
 
 Do **not** use for:
 - `docs/standards/*` (English only)
@@ -26,6 +27,24 @@ Do **not** reference any file under gitignored working-memory directories
 (`docs/marketing/`, `docs/analysis/`) from the bilingual docs you edit —
 those paths are local-only and won't resolve in fresh clones.
 
+**`docs/usermanuals/` is link-isolated.** Pages there feed the static-site
+SPA viewer (`site/usermanual.html`), which only renders SPA hash-router
+routes (`#/<section>/<page>`) and external HTTPS URLs. Repo-relative
+links like `../../../guides/foo.md` or even intra-manual paths like
+`../concepts/choosing-trainer.md` 404 in the SPA. When you edit a
+usermanual page, every link MUST be one of:
+
+1. A SPA route `#/<section>/<page>` where the target file exists under
+   `docs/usermanuals/<lang>/<section>/<page>.md`.
+2. An absolute HTTPS URL (use `https://github.com/cemililik/ForgeLM/blob/main/<path>`
+   for project files that live outside the manual — guides, references,
+   QMS templates, source files, the roadmap).
+3. A pure same-file anchor (`#heading-slug`).
+
+The guard `tools/check_usermanual_self_contained.py --strict` enforces
+this; see `docs/standards/documentation.md` "User-manual link discipline"
+for the full ruleset.
+
 ## Required reading
 
 1. [docs/standards/localization.md](../../../docs/standards/localization.md) — the full policy

.claude/skills/sync-bilingual-docs/SKILL.md

@@ -14,6 +14,7 @@ Any change to these paths or their siblings:
 - `docs/product_strategy.md` / `product_strategy-tr.md`
 - `docs/roadmap.md` / `roadmap-tr.md`
 - `docs/reference/*.md` (has matching `-tr.md`)
+- `docs/usermanuals/{en,tr}/**/*.md` (the static-site SPA viewer source)
 
 Do **not** use for:
 - `docs/standards/*` (English only)
@@ -26,6 +27,24 @@ Do **not** reference any file under gitignored working-memory directories
 (`docs/marketing/`, `docs/analysis/`) from the bilingual docs you edit —
 those paths are local-only and won't resolve in fresh clones.
 
+**`docs/usermanuals/` is link-isolated.** Pages there feed the static-site
+SPA viewer (`site/usermanual.html`), which only renders SPA hash-router
+routes (`#/<section>/<page>`) and external HTTPS URLs. Repo-relative
+links like `../../../guides/foo.md` or even intra-manual paths like
+`../concepts/choosing-trainer.md` 404 in the SPA. When you edit a
+usermanual page, every link MUST be one of:
+
+1. A SPA route `#/<section>/<page>` where the target file exists under
+   `docs/usermanuals/<lang>/<section>/<page>.md`.
+2. An absolute HTTPS URL (use `https://github.com/cemililik/ForgeLM/blob/main/<path>`
+   for project files that live outside the manual — guides, references,
+   QMS templates, source files, the roadmap).
+3. A pure same-file anchor (`#heading-slug`).
+
+The guard `tools/check_usermanual_self_contained.py --strict` enforces
+this; see `docs/standards/documentation.md` "User-manual link discipline"
+for the full ruleset.
+
 ## Required reading
 
 1. [docs/standards/localization.md](../../../docs/standards/localization.md) — the full policy

.github/workflows/ci.yml

@@ -239,6 +239,20 @@ jobs:
         # to ``monkeypatch.delitem`` (auto-restores on teardown).
         run: python3 tools/check_no_unguarded_sys_modules_pop.py
 
+      - name: User-manual self-contained link guard (strict)
+        # Post-v0.7.0 cycle: the docs/usermanuals/ tree is the source of
+        # truth for the static-site SPA viewer (site/usermanual.html +
+        # site/js/guide.js).  The viewer only resolves SPA hash-router
+        # routes ``#/<section>/<page>`` and external HTTPS URLs.
+        # Anything else — repo-relative ``../../../guides/...`` paths,
+        # intra-manual ``../section/page.md`` paths, SPA routes that
+        # point at a non-existent page — 404s when the user clicks.
+        # This guard walks every *.md under docs/usermanuals/ and
+        # fails the gate on any link that would break in the SPA.
+        # See docs/standards/documentation.md "User-manual link
+        # discipline" for the full ruleset.
+        run: python3 tools/check_usermanual_self_contained.py --strict
+
       - name: License check
         run: |
           test -f LICENSE || (echo "LICENSE file missing" && exit 1)

.markdownlint.json

@@ -4,9 +4,11 @@
   "//2": "MD014 (commands-show-output): shell examples in operator docs deliberately show only the command (`$ forgelm audit ...`) without sample output — output snippets rot quickly across versions and would force a doc update on every CLI banner change.",
   "//3": "MD013 (line-length): bilingual (EN+TR) reference + design docs intentionally carry long lines for paragraph-style explanations, table cells, and prose with long inline links. The 80-col limit is a code-style holdover that hurts readability of documentation; the project's bilingual_parity guard already enforces structural alignment, and the rest of the prose stays human-readable at any reasonable width.",
   "//4": "MD025 (single-h1): docs/usermanuals/<lang>/<section>/<page>.md pages use a YAML frontmatter `title:` AND a body `# Heading` by design — the frontmatter title feeds the sidebar nav and SPA page title, the body H1 is the visible page heading. Every page in docs/usermanuals/ follows this pattern; disabling MD025 keeps the established docs convention intact.",
+  "//5": "MD024 (no-duplicate-heading) is restricted to siblings only: docs/roadmap/releases.md, CHANGELOG.md, and similar release-history files repeat the same H3 names (`Summary`, `Highlights`, `Public surface changes`, `Full changelog`) under each release's H2 by design. Same-parent duplicates remain a hard error.",
   "default": true,
   "MD051": false,
   "MD014": false,
   "MD013": false,
-  "MD025": false
+  "MD025": false,
+  "MD024": { "siblings_only": true }
 }

AGENTS.md

@@ -4,7 +4,7 @@
 
 ## What ForgeLM is (in one line)
 
-A **config-driven, enterprise-grade LLM fine-tuning toolkit** — YAML in, fine-tuned model + compliance artifacts out. Built for CI/CD pipelines, not notebooks. Covers SFT → DPO → SimPO → KTO → ORPO → GRPO, with integrated safety evaluation, EU AI Act compliance, and auto-revert on quality regression.
+A **config-driven, enterprise-grade LLM fine-tuning toolkit** — YAML in, fine-tuned model + compliance artifacts out. Drives the same workflow from a terminal, a notebook, or a CI/CD pipeline step. Covers SFT → DPO → SimPO → KTO → ORPO → GRPO, with integrated safety evaluation, EU AI Act compliance, and auto-revert on quality regression.
 
 Not a framework for training from scratch. Not an inference engine. Not a GUI. Read [docs/product_strategy.md](docs/product_strategy.md) for the 5-minute background.
 
@@ -76,6 +76,7 @@ ForgeLM/
 │                            # check_bilingual_parity, check_cli_help_consistency,
 │                            # check_field_descriptions, check_no_analysis_refs,
 │                            # check_pip_audit, check_bandit, check_site_claims,
+│                            # check_usermanual_self_contained,
 │                            # check_wizard_defaults_sync, generate_sbom,
 │                            # generate_wizard_defaults, build_usermanuals
 ├── docs/
@@ -156,10 +157,11 @@ Default workflow for a non-trivial change:
      python3 tools/check_wizard_defaults_sync.py && \
      python3 tools/check_no_analysis_refs.py && \
      python3 tools/check_no_unguarded_sys_modules_pop.py && \
+     python3 tools/check_usermanual_self_contained.py --strict && \
      python3 tools/update_site_version.py --check
    ```
 
-   All eleven must pass. The first four are the historical gauntlet;
+   All twelve must pass. The first four are the historical gauntlet;
    the three doc guards (Wave 3 / Wave 4 / Wave 5 additions) catch
    bilingual structural drift, broken markdown anchors, and CLI ↔ docs
    help-text drift before the PR opens. The wizard-defaults guard
@@ -172,12 +174,18 @@ Default workflow for a non-trivial change:
    `sys.modules.pop("torch"|"numpy"|"trl"|…)` without
    `monkeypatch.delitem` — the v0.5.7 round-3 review traced 35
    spurious full-suite failures to that exact pattern.  The
-   site-version guard (v0.6.0 retag cycle) re-derives the marketing
-   site's displayed version from CHANGELOG's latest released header
-   and fails the PR if any of the 15+ literals across `site/*.html`
-   and `site/js/translations.js` has drifted; the v0.5.5 → v0.6.0
-   release shipped with the hero badge still reading `v0.5.5`, which
-   this guard now prevents.
+   usermanual self-contained guard (post-v0.7.0 cycle) blocks any
+   link inside `docs/usermanuals/` that would 404 in the static SPA
+   viewer: every link must be either a `#/<section>/<page>` SPA
+   route backed by a real manual page or an absolute HTTPS URL.
+   Repo-relative `../../../guides/...` references fail the gate —
+   see `docs/standards/documentation.md` "User-manual link
+   discipline".  The site-version guard (v0.6.0 retag cycle)
+   re-derives the marketing site's displayed version from CHANGELOG's
+   latest released header and fails the PR if any of the 15+ literals
+   across `site/*.html` and `site/js/translations.js` has drifted; the
+   v0.5.5 → v0.6.0 release shipped with the hero badge still reading
+   `v0.5.5`, which this guard now prevents.
 
 ## Etiquette when communicating with the user
 

CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## What ForgeLM is (in one line)
 
-A **config-driven, enterprise-grade LLM fine-tuning toolkit** — YAML in, fine-tuned model + compliance artifacts out. Built for CI/CD pipelines, not notebooks. Covers SFT → DPO → SimPO → KTO → ORPO → GRPO, with integrated safety evaluation, EU AI Act compliance, and auto-revert on quality regression.
+A **config-driven, enterprise-grade LLM fine-tuning toolkit** — YAML in, fine-tuned model + compliance artifacts out. Drives the same workflow from a terminal, a notebook, or a CI/CD pipeline step. Covers SFT → DPO → SimPO → KTO → ORPO → GRPO, with integrated safety evaluation, EU AI Act compliance, and auto-revert on quality regression.
 
 Not a framework for training from scratch. Not an inference engine. Not a GUI. Read [docs/product_strategy.md](docs/product_strategy.md) for the 5-minute background.
 
@@ -76,6 +76,7 @@ ForgeLM/
 │                            # check_bilingual_parity, check_cli_help_consistency,
 │                            # check_field_descriptions, check_no_analysis_refs,
 │                            # check_pip_audit, check_bandit, check_site_claims,
+│                            # check_usermanual_self_contained,
 │                            # check_wizard_defaults_sync, generate_sbom,
 │                            # generate_wizard_defaults, build_usermanuals
 ├── docs/
@@ -156,10 +157,11 @@ Default workflow for a non-trivial change:
      python3 tools/check_wizard_defaults_sync.py && \
      python3 tools/check_no_analysis_refs.py && \
      python3 tools/check_no_unguarded_sys_modules_pop.py && \
+     python3 tools/check_usermanual_self_contained.py --strict && \
      python3 tools/update_site_version.py --check
    ```
 
-   All eleven must pass. The first four are the historical gauntlet;
+   All twelve must pass. The first four are the historical gauntlet;
    the three doc guards (Wave 3 / Wave 4 / Wave 5 additions) catch
    bilingual structural drift, broken markdown anchors, and CLI ↔ docs
    help-text drift before the PR opens. The wizard-defaults guard
@@ -172,12 +174,18 @@ Default workflow for a non-trivial change:
    `sys.modules.pop("torch"|"numpy"|"trl"|…)` without
    `monkeypatch.delitem` — the v0.5.7 round-3 review traced 35
    spurious full-suite failures to that exact pattern.  The
-   site-version guard (v0.6.0 retag cycle) re-derives the marketing
-   site's displayed version from CHANGELOG's latest released header
-   and fails the PR if any of the 15+ literals across `site/*.html`
-   and `site/js/translations.js` has drifted; the v0.5.5 → v0.6.0
-   release shipped with the hero badge still reading `v0.5.5`, which
-   this guard now prevents.
+   usermanual self-contained guard (post-v0.7.0 cycle) blocks any
+   link inside `docs/usermanuals/` that would 404 in the static SPA
+   viewer: every link must be either a `#/<section>/<page>` SPA
+   route backed by a real manual page or an absolute HTTPS URL.
+   Repo-relative `../../../guides/...` references fail the gate —
+   see `docs/standards/documentation.md` "User-manual link
+   discipline".  The site-version guard (v0.6.0 retag cycle)
+   re-derives the marketing site's displayed version from CHANGELOG's
+   latest released header and fails the PR if any of the 15+ literals
+   across `site/*.html` and `site/js/translations.js` has drifted; the
+   v0.5.5 → v0.6.0 release shipped with the hero badge still reading
+   `v0.5.5`, which this guard now prevents.
 
 ## Etiquette when communicating with the user