fix: qualify Delivery sources and preserve compatibility

README.md

@@ -1,4 +1,4 @@
-# documentation-docusaurus
+# documentation-docusaurus-vssa
 
 VSSA-managed Hermes skill for the complete Docusaurus documentation lifecycle:
 
@@ -13,8 +13,10 @@ VSSA-managed Hermes skill for the complete Docusaurus documentation lifecycle:
 
 - Gitea: <https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus>
 - Branch: `main`
-- Maintainer worktree: `/opt/data/documentation-docusaurus-skill`
+- Runtime package: `documentation-docusaurus-vssa` (complete repository package).
-- Runtime installation: `/opt/data/skills/productivity/documentation-docusaurus` → maintainer worktree
+- Compatibility: install `compatibility/documentation-docusaurus.md` as `documentation-docusaurus/SKILL.md`; old callers still load this VSSA adoption.
+- Generic owner: `documentation-docusaurus-global`, from the distinct `home-v1-skills-code-agent/documentation-docusaurus` repository.
+- Repository URL and all VSSA-specific reference content remain independently maintained.
 
 ## Validate
 

SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: documentation-docusaurus
+name: documentation-docusaurus-vssa
 description: >
   Opinionated Docusaurus v3 guidance using Diátaxis. Use when creating or restructuring documentation,
   writing MDX, configuring navigation or deployment, building evidence registries and local YAML data,
@@ -11,7 +11,7 @@ description: >
 license: MIT
 metadata:
   author: workspace-skills-code-agent
-  version: "2.0"
+  version: "2.1"
   spec: agentskills.io/specification
   framework: Diátaxis
   hermes:
@@ -28,12 +28,15 @@ compatibility: Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub
 
 This VSSA-managed skill is maintained in Gitea at
 `https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus`.
-Treat repository `main` as the source of truth. The maintainer worktree is
+Treat repository `main` as the source of truth. Install the complete published package under `documentation-docusaurus-vssa`.
-`/opt/data/documentation-docusaurus-skill`, and the runtime installation is a symlink to that
+Install `compatibility/documentation-docusaurus.md` as the legacy
-worktree. For every reusable improvement: fetch and fast-forward, edit the repository package,
+`documentation-docusaurus/SKILL.md` compatibility route; existing callers keep VSSA behavior.
+Generic guidance instead loads `documentation-docusaurus-global` from
+https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus.
+Do not overwrite either source with the other. For every reusable improvement: fetch and fast-forward, edit the repository package,
 run `python3 scripts/validate_skill.py`, review the complete diff, commit and push, verify exact ref
 equality and authenticated remote readback, require the exact-SHA Gitea Actions task to succeed, and
-then verify `skill_view(name='documentation-docusaurus')` loads the changed package. Never maintain a
+then verify `skill_view(name='documentation-docusaurus-vssa')` loads the changed package. Never maintain a
 divergent runtime-only copy.
 
 This repository is an independent VSSA adoption. Upstream or project-specific skill repositories are

compatibility/documentation-docusaurus.md

@@ -0,0 +1,19 @@
+---
+name: documentation-docusaurus
+description: Compatibility alias for the VSSA Docusaurus adoption.
+version: 1.0.0
+license: MIT
+metadata:
+  hermes:
+    related_skills: [documentation-docusaurus-vssa]
+---
+
+# VSSA Docusaurus compatibility route
+
+Load `documentation-docusaurus-vssa` before performing documentation work.
+Its complete package is maintained at
+https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus.
+For a legacy reference-file request, load the same relative reference path from
+`documentation-docusaurus-vssa`. Do not substitute generic guidance for VSSA content.
+Generic guidance has the distinct name `documentation-docusaurus-global` at
+https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus.

references/drawio-source-diagrams.md

@@ -8,7 +8,7 @@ Use this workflow when a Docusaurus v3 site must render an editable Draw.io sour
 - Render that source directly in MDX; do not make a PNG/SVG export the only authoritative artifact.
 - Keep the source adjacent to, or in a clearly named diagram directory near, the page that consumes it.
 - Use the global `diagrams-drawio` skill to author and validate diagram content.
-- Use this `documentation-docusaurus` skill to onboard and render the source in Docusaurus.
+- Use this `documentation-docusaurus-vssa` skill to onboard and render the source in Docusaurus.
 
 Recommended layout:
 

scripts/validate_skill.py

@@ -10,8 +10,12 @@ assert text.startswith("---\n"), "SKILL.md must start with YAML frontmatter"
 parts = text.split("\n---\n", 1)
 assert len(parts) == 2 and parts[1].strip(), "frontmatter must close and body must be non-empty"
 frontmatter, body = parts
-assert re.search(r"^name:\s*documentation-docusaurus\s*$", frontmatter, re.M), "wrong skill name"
+assert re.search(r"^name:\s*documentation-docusaurus-vssa\s*$", frontmatter, re.M), "wrong skill name"
 assert "description:" in frontmatter, "missing description"
+alias = (ROOT / "compatibility/documentation-docusaurus.md").read_text()
+assert "name: documentation-docusaurus\n" in alias
+assert "Load `documentation-docusaurus-vssa`" in alias
+assert "documentation-docusaurus-global" in alias
 assert len(text) <= 100_000, "SKILL.md exceeds Hermes size limit"
 assert "## Authoritative repository" in body
 assert "## Gitea delivery gate" in body
@@ -47,6 +51,6 @@ unreferenced = sorted(name for name in reference_names if name not in coverage_t
 assert not unreferenced, f"unreferenced support files: {unreferenced}"
 
 print(
-    f"OK skill=documentation-docusaurus chars={len(text)} "
+    f"OK skill=documentation-docusaurus-vssa chars={len(text)} "
     f"references={len(reference_names)} markdown_files={len(markdown_files)}"
 )