@tidyfactor/doc 1.3.0 → 1.9.0

package/references/workflows/generate-adr.md

@@ -0,0 +1,41 @@
+# Workflow: generate-adr
+
+One outcome: an Architectural Decision Record saved to `docs/adr/NNNN-<slug>.md` and indexed in `docs/adr/README.md`, adhering to the MADR (Markdown Architectural Decision Records) standard.
+
+## Steps
+
+1. **Initialize ADR Directory & Determine Sequence**:
+   - Ensure `docs/adr/` exists.
+   - Scan existing files matching `docs/adr/NNNN-*.md`.
+   - Calculate next number: `0001` if empty, or increment highest existing number (e.g. `0002`, `0003`).
+
+2. **Establish Context & Problem Statement**:
+   - State the technical context clearly: What engineering problem or architectural need forced a decision?
+   - Identify Decision Drivers: Performance, developer experience, zero-runtime overhead, license compatibility, RTL support, security.
+
+3. **Formulate Considered Options**:
+   - List at least 2–3 viable alternatives (e.g. VitePress vs. MkDocs Material vs. Docsify; Medoo vs. Doctrine vs. Eloquent).
+   - For every option, provide an objective Pros & Cons analysis based on verifiable engineering facts.
+
+4. **Document Decision Outcome & Rationale**:
+   - Selected option: `Chosen option: [Option Name], because [positive arguments]`.
+   - Explain why alternatives were rejected without emotional bias.
+
+5. **Map Consequences & System Impact**:
+   - **Positive consequences**: Capabilities gained, performance improvements, simplified maintenance.
+   - **Negative consequences / Trade-offs**: Learning curve, dependencies introduced, migration effort.
+   - **Mitigation plan**: How trade-offs will be handled.
+
+6. **Write ADR & Update Index**:
+   - Write file `docs/adr/NNNN-<slug>.md` using `memory/adr-template.md`.
+   - Update `docs/adr/README.md` table of contents with status, title, and date.
+   - Run `python scripts/audit_docs.py docs/adr/` to verify link and credential hygiene.
+
+## Validation checklist
+
+- [ ] ADR file exists at `docs/adr/NNNN-<slug>.md` with 4-digit sequential numbering.
+- [ ] Conforms strictly to MADR structure in `memory/adr-template.md`.
+- [ ] At least two realistic alternatives were evaluated with pros/cons.
+- [ ] Tone conforms to `memory/tone-of-voice.md` (objective, technical, zero marketing fluff).
+- [ ] `docs/adr/README.md` index includes the new record.
+- [ ] Audited with `python scripts/audit_docs.py docs/adr/` and passed 100/100.

package/references/workflows/generate-changelog.md

@@ -0,0 +1,52 @@
+# Workflow: generate-changelog
+
+One outcome: a project-root `CHANGELOG.md` created or updated strictly conforming to **Keep a Changelog v1.1.0** and **SemVer 2.0.0**. Along with `README.md`, this is the authoritative Single Source of Truth (SSOT) for version releases, changes, and migration notes.
+
+## Steps
+
+1. **Locate or initialize `CHANGELOG.md`**:
+   - Check if `CHANGELOG.md` exists at the project root.
+   - If missing, load the Keep a Changelog template from `../memory/doc-templates.md` and initialize with standard header, description, and link definitions.
+
+2. **Extract change history & commit deltas**:
+   - Inspect git commit history:
+     ```bash
+     git log --oneline --no-merges -n 50
+     # Or between tags:
+     git log <last-tag>..HEAD --oneline
+     ```
+   - Parse Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `perf:`, `chore:`, `sec:`).
+   - If non-git or manual changes are provided, align them with the verified codebase changes.
+
+3. **Categorize entries into Keep a Changelog standard sections**:
+   - `### 🚀 Added`: For new features, commands, or capabilities.
+   - `### 🔄 Changed`: For changes in existing functionality, refactors, or UX enhancements.
+   - `### ⚠️ Deprecated`: For once-stable features slated for removal in upcoming releases.
+   - `### 🗑️ Removed`: For features, deprecated APIs, or obsolete assets removed in this release.
+   - `### 🐛 Fixed`: For any bug fixes, link repairs, or error resolutions.
+   - `### 🔒 Security`: In case of vulnerability patches or credential hardening.
+
+4. **Determine SemVer version bump**:
+   - Load `../memory/changelog-rules.md`.
+   - `MAJOR` (X.0.0): Any breaking change or incompatible API/workflow modification.
+   - `MINOR` (0.X.0): Backward-compatible new features, commands, or workflows.
+   - `PATCH` (0.0.X): Backward-compatible bug fixes, link corrections, or documentation polish.
+
+5. **Format the version entry**:
+   - Structure: `## [X.Y.Z] - YYYY-MM-DD` (e.g. `## [1.8.0] - 2026-09-09`).
+   - If drafting work-in-progress, record changes under `## [Unreleased]`.
+   - Maintain strict reverse-chronological order (newest release at the top).
+
+6. **Validate & update metadata**:
+   - Run `python scripts/audit_docs.py CHANGELOG.md` to guarantee zero absolute machine URLs or credential leaks.
+   - Ensure atomic synchronization with `package.json`, `.tidyfactor`, `brand.yaml`, `brand.json`, and `README.md`.
+
+## Validation checklist
+
+- [ ] `CHANGELOG.md` exists at project root and follows Keep a Changelog v1.1.0 format
+- [ ] Version header strictly matches `## [X.Y.Z] - YYYY-MM-DD` or `## [Unreleased]`
+- [ ] All entries classified under valid sections (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`)
+- [ ] Entries are organized in reverse chronological order
+- [ ] SemVer bump is fully justified by the logged changes (Breaking → Major, Feat → Minor, Fix → Patch)
+- [ ] Zero sensitive data, API tokens, passwords, or absolute workstation paths (`file:///`) present
+- [ ] Audited with `python scripts/audit_docs.py CHANGELOG.md` and passed cleanly

package/references/workflows/init-docs.md

@@ -1,18 +1,44 @@
-# Workflow: init-docs
-
-One outcome: a working `/docs` scaffold plus a doc manifest, ready for `collect` and `generate` to populate.
-
-## Steps
-
-1. **Detect the stack(s) present** in the project root — PHP (`composer.json`), JS/TS (`package.json`, `tsconfig.json`), and any of React/Vue/Next (framework deps or config files). Note more than one if the project is mixed (e.g., a PHP API with a React front end).
-2. **Create the folder tree** exactly per `memory/doc-tree.md` — no extra top-level folders, no missing ones. Do not create a folder for a doc type the project doesn't have yet (e.g., skip `docs/api/` for a project with no API surface) — see the "No Empty Structures" note in `doc-tree.md`.
-3. **Write `docs/.doc-manifest.json`** using the schema in `memory/doc-tree.md`, pre-filled with: detected stack(s), project name (from `composer.json`/`package.json`), and empty `collected` / `generated` tracking sections.
-4. **Write a placeholder `docs/README.md` index** (one paragraph: what this `/docs` folder contains, and a note that it's generated/maintained by TidyFactor Doc) — this is the doc-site landing page, distinct from the project-root `README.md`.
-5. **Report** what was created and what stack(s) were detected, and suggest `collect` as the next step.
-
-## Validation checklist
-
-- [ ] `/docs` exists with only the subfolders `doc-tree.md` calls for given the detected stack(s) — nothing extra, nothing missing
-- [ ] `docs/.doc-manifest.json` exists, is valid JSON, and matches the schema in `memory/doc-tree.md`
-- [ ] `docs/README.md` (doc-site index) exists and is distinct in content from any project-root `README.md`
-- [ ] No API/inline/guide content was written — this workflow scaffolds only
+# Workflow: init-docs
+
+One outcome: a working `/docs` scaffold plus an aligned doc manifest, ready for `collect` and `generate` to populate.
+
+---
+
+## 📋 Step 0: Context Delta Resolution (CDL v2.0)
+
+Before prompting the user for documentation configuration, execute the mechanical resolution formula:
+
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+
+1. **Auto-Sensing on Disk**:
+   - `doc_engine`: Check for existing `mkdocs.yml` (selects `mkdocs_material`) or `docs/index.html` (selects `docsify_spa`). If neither exists, default to `mkdocs_material`.
+   - `target_scope`: Check project structure or `docs/.doc-manifest.json` (defaults to `full_codebase`).
+   - `audience_persona`: Read `brand.yaml` (or fallback `brand.json`) for `audience` / persona. If absent, default to `bilingual_developer`.
+   - For file sources marked with `track_staleness: true`, compare file hash/mtime against `.tidyfactor/doc-brief.snapshot.yaml`.
+2. **Fail-Open Brain MCP Acceleration**:
+   - Query `search_knowledge_base(query="documentation stack audience", scope="project")`.
+   - If Brain MCP is offline or returns empty, fail open silently (0ms latency penalty).
+3. **Structured Interactive Disclosure (DM-DA Mode A)**:
+   - Present any genuine $\text{Unknowns}$ in a crisp, non-robotic prompt with clear A/B/C/D choices and recommended defaults.
+   - Zero robotic preambles or lectures.
+4. **Local Snapshot Persistence (Anti-Dual-Write)**:
+   - Persist confirmed parameters to `.tidyfactor/doc-brief.snapshot.yaml`.
+
+---
+
+## 🛠️ Execution Steps
+
+1. **Detect the stack(s) present** in the project root — PHP (`composer.json`), JS/TS (`package.json`, `tsconfig.json`), and any of React/Vue/Next (framework deps or config files). Note more than one if the project is mixed (e.g., a PHP API with a React front end).
+2. **Create the folder tree** exactly per `memory/doc-tree.md` — no extra top-level folders, no missing ones. Do not create a folder for a doc type the project doesn't have yet (e.g., skip `docs/api/` for a project with no API surface) — see the "No Empty Structures" note in `doc-tree.md`.
+3. **Write `docs/.doc-manifest.json`** using the schema in `memory/doc-tree.md`, pre-filled with: detected stack(s), project name (from `composer.json`/`package.json`), confirmed engine/audience from Step 0, and empty `collected` / `generated` tracking sections.
+4. **Write a placeholder `docs/README.md` index** (one paragraph: what this `/docs` folder contains, and a note that it's generated/maintained by TidyFactor Doc) — this is the doc-site landing page, distinct from the project-root `README.md`.
+5. **Report** what was created and what stack(s) were detected, and suggest `collect` as the next step.
+
+## Validation checklist
+
+- [ ] Evaluated Context Delta Resolution formula before prompting user
+- [ ] Local decision snapshot persisted to `.tidyfactor/doc-brief.snapshot.yaml`
+- [ ] `/docs` exists with only the subfolders `doc-tree.md` calls for given the detected stack(s) — nothing extra, nothing missing
+- [ ] `docs/.doc-manifest.json` exists, is valid JSON, and matches the schema in `memory/doc-tree.md`
+- [ ] `docs/README.md` (doc-site index) exists and is distinct in content from any project-root `README.md`
+- [ ] No API/inline/guide content was written — this workflow scaffolds only

package/references/workflows/vitepress.md

@@ -0,0 +1,57 @@
+# Workflow: vitepress
+
+One outcome: A fully compiled, statically hosted VitePress documentation portal with custom luxury typography, surgical RTL flex order, and multi-language routing configured per `memory/vitepress-config.md`.
+
+---
+
+## Steps
+
+1. **Verify Environment & Dependencies:**
+   - Run `node --version` (require >= 18).
+   - Install VitePress: `npm install -D vitepress` (or verify package.json has `"vitepress": "^1.6.0"`).
+   - Inject doc scripts into root `package.json`:
+     ```json
+     "scripts": {
+       "docs:dev": "vitepress dev docs",
+       "docs:build": "vitepress build docs",
+       "docs:preview": "vitepress preview docs"
+     }
+     ```
+
+2. **Scaffold Directory Tree & Assets:**
+   - Ensure documentation markdown lives in `docs/`.
+   - Create `docs/.vitepress/config.mjs` using the master schema in `memory/vitepress-config.md`.
+   - Create `docs/.vitepress/theme/index.mjs` registering `custom.css`.
+   - Copy brand logo to `docs/public/logo.png`.
+
+3. **Configure Multi-Language Subdirectory Routing:**
+   - Enforce dedicated subdirectories for every supported locale to eliminate 404s:
+     - Arabic (Native Root): `docs/index.md`
+     - English: `docs/en/index.md`
+     - Additional growth locales: `docs/es/`, `docs/de/`, `docs/fr/`, `docs/pt/`, `docs/zh/`, `docs/fa/`.
+
+4. **Inject Luxury CSS & RTL Precision:**
+   - Write `docs/.vitepress/theme/custom.css` embedding Alexandria, Cairo, and JetBrains Mono fonts.
+   - Configure surgical RTL navbar flex order:
+     - Title/Logo (`order: 1`), Menu (`order: 2` with `margin-inline-end: auto`), Search (`order: 3`), Translations (`order: 4`), Appearance (`order: 5`), Social (`order: 6`).
+   - Align Hero reading hierarchy: Text on the right (`order: 1`), Logo on the left (`order: 2`).
+   - Protect Hero Action Buttons (CTAs): single-row layout (`flex-wrap: nowrap !important; white-space: nowrap !important`).
+   - Fix 3-Column Feature Cards: explicitly size `.VPFeatures .item` (`width: 33.333333% !important`) and apply `direction: rtl !important; unicode-bidi: plaintext !important` to prevent text or parentheses inversion.
+
+5. **Build & Validate:**
+   - Run `npm run docs:build` (must complete with **zero errors and zero broken links**).
+
+6. **Report Deployment Instructions:**
+   - Local dev server: `npm run docs:dev` (runs at `http://localhost:5173`).
+   - Production bundle: deploy the compiled output directory `docs/.vitepress/dist/`.
+
+---
+
+## Validation Checklist
+
+- [ ] `docs/.vitepress/config.mjs` exists with valid ESM syntax and full locales configuration
+- [ ] `docs/.vitepress/theme/custom.css` exists with Alexandria/Cairo fonts, single-row Hero CTAs, and 3-column card widths
+- [ ] Hero layout in RTL displays text/CTAs on the right and logo on the left
+- [ ] Every active locale index (`docs/index.md`, `docs/en/index.md`, etc.) exists on disk
+- [ ] `npm run docs:build` compiles cleanly with **0 errors and 0 dead links**
+- [ ] Clean relative links only — no machine workstation paths (`file:///C:/...`) or hardcoded secrets

package/scripts/audit_docs.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Documentation Quality & Hygiene Auditor
+Deterministic AST and pattern scanner for documentation files under /docs and root README.
+Audits for sensitive data leaks, banned absolute URLs, relative link integrity,
+and Docsify / MkDocs structural requirements.
+"""
+
+import sys
+import os
+import re
+import json
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows console
+if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+SENSITIVE_PATTERNS = [
+    (r"(?i)(password|passwd|pwd)\s*[:=]\s*['\"][^'\"]+['\"]", "Hardcoded plain password"),
+    (r"(?i)(secret_key|secret|api_key|apikey|token)\s*[:=]\s*['\"][a-zA-Z0-9_\-\.]{12,}['\"]", "Hardcoded secret / API token"),
+    (r"(?i)cpanel_[a-zA-Z0-9_]+_pass", "cPanel credential pattern"),
+    (r"(?i)whm_[a-zA-Z0-9_]+_token", "WHM access token pattern"),
+    (r"ghp_[a-zA-Z0-9]{20,}", "GitHub Personal Access Token"),
+    (r"xox[baprs]-[0-9a-zA-Z]{10,}", "Slack Token"),
+    (r"AKIA[0-9A-Z]{16}", "AWS Access Key"),
+]
+
+BANNED_URL_PATTERNS = [
+    (r"file:///[a-zA-Z]:[/\\]", "Banned machine-specific absolute file URL"),
+    (r"file://c:/", "Banned Windows drive path URL"),
+    (r"[a-zA-Z]:\\wamp64\\www\\", "Banned internal workstation local path"),
+]
+
+# Standard Keep a Changelog v1.1.0 sections
+VALID_CHANGELOG_SECTIONS = {"Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"}
+CHANGELOG_VERSION_PATTERN = re.compile(r"^##\s+\[(?:\d+\.\d+\.\d+|Unreleased)\](?:\s+-\s+\d{4}-\d{2}-\d{2})?$")
+
+def audit_doc_file(file_path: Path, check_links: bool = True) -> list:
+    issues = []
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="replace")
+    except Exception as e:
+        return [{"file": str(file_path), "severity": "high", "type": "read_error", "message": str(e)}]
+
+    lines = content.splitlines()
+    is_changelog = file_path.name.lower().startswith("changelog")
+
+    for idx, line in enumerate(lines, start=1):
+        # 1. Check for sensitive data leaks
+        for pattern, desc in SENSITIVE_PATTERNS:
+            if re.search(pattern, line):
+                # Ignore placeholders like YOUR_API_KEY, REDACTED, example
+                if not re.search(r"(?i)(your_|example|redacted|\.\.\.|placeholder|<.+>|dummy)", line):
+                    issues.append({
+                        "file": str(file_path),
+                        "line": idx,
+                        "severity": "critical",
+                        "type": "sensitive_data_leak",
+                        "message": f"Potential sensitive data leak detected: {desc}."
+                    })
+
+        # 2. Check for banned absolute workstation paths & file:/// URLs
+        for pattern, desc in BANNED_URL_PATTERNS:
+            if re.search(pattern, line):
+                # Ignore lines explaining the ban, rule definitions, or dummy placeholders
+                if not re.search(r"(?i)(prohibit|banned|prevent|never|don't|no\s+|avoid|clean relative|mandate|your_|example|redacted|\.\.\.|placeholder|<.+>|dummy)", line):
+                    issues.append({
+                        "file": str(file_path),
+                        "line": idx,
+                        "severity": "high",
+                        "type": "banned_absolute_path",
+                        "message": f"Banned workstation-specific path detected: {desc}. Use clean relative links or public URLs."
+                    })
+
+        # 3. Check relative link integrity (strip code spans first to avoid flagging examples)
+        if check_links:
+            # Remove inline code backticks before checking active markdown links
+            line_no_code = re.sub(r"`[^`]*`", "", line)
+            # Match markdown links: [text](path)
+            for match in re.finditer(r"\[(?:[^\]]*)\]\(([^)]+)\)", line_no_code):
+                target_url = match.group(1).strip()
+                # Skip external, anchor-only, mailto, tel
+                if re.match(r"^(?:https?://|mailto:|tel:|#)", target_url, re.IGNORECASE):
+                    continue
+                # Strip anchor or query params
+                clean_target = target_url.split("#")[0].split("?")[0].strip()
+                if not clean_target:
+                    continue
+                # Resolve relative path
+                resolved = (file_path.parent / clean_target).resolve()
+                if not resolved.exists():
+                    issues.append({
+                        "file": str(file_path),
+                        "line": idx,
+                        "severity": "high",
+                        "type": "broken_relative_link",
+                        "message": f"Broken relative link '{target_url}' — target '{clean_target}' does not exist on disk."
+                    })
+
+    # 4. CHANGELOG.md specific structure validation
+    if is_changelog:
+        version_headers = [l.strip() for l in lines if l.startswith("## ")]
+        if not version_headers:
+            issues.append({
+                "file": str(file_path),
+                "line": 1,
+                "severity": "high",
+                "type": "invalid_changelog_format",
+                "message": "CHANGELOG.md lacks standard release headers (expected format: '## [x.y.z] - YYYY-MM-DD' or '## [Unreleased]')."
+            })
+        else:
+            for vh in version_headers:
+                if not CHANGELOG_VERSION_PATTERN.match(vh):
+                    issues.append({
+                        "file": str(file_path),
+                        "line": 1,
+                        "severity": "low",
+                        "type": "non_standard_version_header",
+                        "message": f"Changelog version header '{vh}' does not strictly match Keep a Changelog SemVer pattern '## [X.Y.Z] - YYYY-MM-DD'."
+                    })
+
+    return issues
+
+def audit_docs_directory(target_dir: Path) -> dict:
+    all_issues = []
+    files_scanned = 0
+
+    if target_dir.is_file():
+        files_to_check = [target_dir]
+    elif target_dir.is_dir():
+        files_to_check = list(target_dir.rglob("*.md"))
+    else:
+        return {"error": f"Target path does not exist: {target_dir}", "passed": False}
+
+    for f in files_to_check:
+        # Skip vendor/node_modules/.git
+        if any(part in f.parts for part in [".git", "node_modules", "dist", "vendor"]):
+            continue
+        files_scanned += 1
+        issues = audit_doc_file(f)
+        all_issues.extend(issues)
+
+    critical_count = len([i for i in all_issues if i.get("severity") == "critical"])
+    high_count = len([i for i in all_issues if i.get("severity") == "high"])
+
+    score = max(0, 100 - (critical_count * 30) - (high_count * 15))
+    passed = critical_count == 0 and high_count == 0
+
+    return {
+        "target": str(target_dir),
+        "files_scanned": files_scanned,
+        "score": score,
+        "passed": passed,
+        "critical_issues": critical_count,
+        "high_issues": high_count,
+        "total_issues": len(all_issues),
+        "issues": all_issues,
+        "timestamp": "2026-09-02T06:00:00Z"
+    }
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Documentation Quality & Hygiene Auditor")
+    parser.add_argument("target", nargs="?", default="docs", help="Directory or markdown file to audit (default: docs)")
+    parser.add_argument("--json", action="store_true", help="Output pure JSON format")
+
+    args = parser.parse_args()
+    target_path = Path(args.target)
+
+    result = audit_docs_directory(target_path)
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        status_str = "[PASS]" if result.get("passed") else "[FAIL]"
+        print(f"\n{status_str} Documentation Quality & Hygiene Audit — Score: {result.get('score', 0)}/100")
+        print(f"Target: {result.get('target')} | Files Scanned: {result.get('files_scanned', 0)}")
+        print(f"Issues Found: {result.get('total_issues', 0)} (Critical: {result.get('critical_issues', 0)}, High: {result.get('high_issues', 0)})\n")
+
+        for iss in result.get("issues", []):
+            print(f"  - [{iss.get('severity', '').upper()}] {iss.get('file')}:{iss.get('line', '?')} — {iss.get('message')}")
+        print()
+
+    sys.exit(0 if result.get("passed") else 1)
+
+if __name__ == "__main__":
+    main()

package/scripts/clean_orphaned_assets.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+TidyFactor Asset Hygiene & Orphan Cleaner
+Scans documentation markdown files for referenced image assets, detects orphaned files
+in assets/ directory, detects duplicate assets via SHA-256 hashing, and evaluates
+potential WebP compression savings.
+"""
+
+import sys
+import os
+import re
+import json
+import hashlib
+import argparse
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows console
+if sys.stdout and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if sys.stderr and hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"}
+
+def get_file_hash(file_path: Path) -> str:
+    hasher = hashlib.sha256()
+    try:
+        with open(file_path, "rb") as f:
+            while chunk := f.read(65536):
+                hasher.update(chunk)
+        return hasher.hexdigest()
+    except Exception:
+        return ""
+
+def scan_markdown_image_references(root_dir: Path) -> set:
+    referenced_filenames = set()
+    md_files = []
+
+    for f in root_dir.rglob("*.md"):
+        if any(part in f.parts for part in [".git", "node_modules", "vendor", "dist"]):
+            continue
+        md_files.append(f)
+
+    for md_file in md_files:
+        try:
+            content = md_file.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            continue
+
+        # 1. Match standard markdown image syntax: ![alt](path)
+        for match in re.finditer(r"!\[(?:[^\]]*)\]\(([^)]+)\)", content):
+            raw_url = match.group(1).strip().split("?")[0].split("#")[0]
+            if raw_url.startswith(("http://", "https://", "data:")):
+                continue
+            referenced_filenames.add(Path(raw_url).name.lower())
+
+        # 2. Match HTML img tags: <img src="path" ... />
+        for match in re.finditer(r"""<img[^>]+src=["']([^"']+)["']""", content, re.IGNORECASE):
+            raw_url = match.group(1).strip().split("?")[0].split("#")[0]
+            if raw_url.startswith(("http://", "https://", "data:")):
+                continue
+            referenced_filenames.add(Path(raw_url).name.lower())
+
+    return referenced_filenames
+
+def analyze_assets(repo_root: Path, assets_dir: Path, delete_orphans: bool = False) -> dict:
+    if not assets_dir.exists() or not assets_dir.is_dir():
+        return {"error": f"Assets directory not found: {assets_dir}", "passed": True, "assets": []}
+
+    referenced_names = scan_markdown_image_references(repo_root)
+
+    asset_files = []
+    for f in assets_dir.iterdir():
+        if f.is_file() and f.suffix.lower() in IMAGE_EXTENSIONS:
+            asset_files.append(f)
+
+    # 1. Detect duplicates via SHA-256
+    hash_map = {}
+    duplicates = []
+    orphaned_files = []
+    webp_candidates = []
+    total_size = 0
+
+    for f in asset_files:
+        size = f.stat().st_size
+        total_size += size
+        f_hash = get_file_hash(f)
+        f_name_lower = f.name.lower()
+
+        if f_hash in hash_map:
+            duplicates.append({
+                "file": str(f.relative_to(repo_root)),
+                "duplicate_of": str(hash_map[f_hash]["path"].relative_to(repo_root)),
+                "size_bytes": size,
+                "sha256": f_hash
+            })
+        else:
+            hash_map[f_hash] = {"path": f, "size": size}
+
+        # Check orphan status
+        is_referenced = f_name_lower in referenced_names
+        if not is_referenced:
+            orphaned_files.append({
+                "file": str(f.relative_to(repo_root)),
+                "size_bytes": size,
+                "deleted": False
+            })
+
+        # Check WebP optimization candidate (PNG/JPG > 50KB)
+        if f.suffix.lower() in {".png", ".jpg", ".jpeg"} and size > 51200:
+            estimated_webp_size = int(size * 0.25) # ~75% reduction
+            webp_candidates.append({
+                "file": str(f.relative_to(repo_root)),
+                "current_size_bytes": size,
+                "estimated_webp_bytes": estimated_webp_size,
+                "estimated_savings_bytes": size - estimated_webp_size
+            })
+
+    # Execute deletion if requested
+    if delete_orphans and orphaned_files:
+        for item in orphaned_files:
+            try:
+                target_to_del = repo_root / item["file"]
+                target_to_del.unlink()
+                item["deleted"] = True
+            except Exception as e:
+                item["delete_error"] = str(e)
+
+    passed = len(orphaned_files) == 0 and len(duplicates) == 0
+
+    return {
+        "repo_root": str(repo_root),
+        "assets_dir": str(assets_dir),
+        "total_assets_scanned": len(asset_files),
+        "total_size_bytes": total_size,
+        "orphaned_count": len(orphaned_files),
+        "orphaned_files": orphaned_files,
+        "duplicates_count": len(duplicates),
+        "duplicates": duplicates,
+        "webp_optimization_candidates": webp_candidates,
+        "passed": passed
+    }
+
+def main():
+    parser = argparse.ArgumentParser(description="TidyFactor Asset Hygiene & Orphan Cleaner")
+    parser.add_argument("repo_root", nargs="?", default=".", help="Root directory of the skill or repo (default: .)")
+    parser.add_argument("--assets-dir", default="assets", help="Relative path to assets directory (default: assets)")
+    parser.add_argument("--delete-orphans", action="store_true", help="Delete orphaned asset files directly")
+    parser.add_argument("--json", action="store_true", help="Output pure JSON format")
+
+    args = parser.parse_args()
+    root_path = Path(args.repo_root).resolve()
+    assets_path = (root_path / args.assets_dir).resolve()
+
+    result = analyze_assets(root_path, assets_path, delete_orphans=args.delete_orphans)
+
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        status_str = "[PASS]" if result.get("passed") else "[WARN]"
+        print(f"\n{status_str} Asset Hygiene & Orphan Scanner — Scanned: {result.get('total_assets_scanned', 0)} assets ({result.get('total_size_bytes', 0):,} bytes)")
+        print(f"Orphaned Assets: {result.get('orphaned_count', 0)} | Duplicate Assets: {result.get('duplicates_count', 0)}\n")
+
+        if result.get("duplicates"):
+            print("  ⚠️ Duplicate Assets Found:")
+            for d in result["duplicates"]:
+                print(f"    - {d['file']} (Duplicate of {d['duplicate_of']}, size: {d['size_bytes']:,} B)")
+
+        if result.get("orphaned_files"):
+            print("  ⚠️ Orphaned Assets (Not linked in any .md):")
+            for o in result["orphaned_files"]:
+                del_str = " [DELETED]" if o.get("deleted") else ""
+                print(f"    - {o['file']} ({o['size_bytes']:,} B){del_str}")
+
+        if result.get("webp_optimization_candidates"):
+            print("\n  💡 WebP Optimization Recommendations (>50KB PNG/JPG):")
+            for w in result["webp_optimization_candidates"]:
+                print(f"    - {w['file']} (Current: {w['current_size_bytes']:,} B -> Est. WebP: {w['estimated_webp_bytes']:,} B, Save: ~{w['estimated_savings_bytes']:,} B)")
+
+        print()
+
+    sys.exit(0 if result.get("passed") else 1)
+
+if __name__ == "__main__":
+    main()

package/tools/build-skill.js

@@ -23,9 +23,12 @@ const OUT_FILE =
 const ROOT_COPIES = [
   "SKILL.md",
   "references",
+  "scripts",
+  "manifest.json",
   "tools",
   "bin",
   "brand.json",
+  "brand.yaml",
   ".tidyfactor",
   "package.json",
   "AGENTS.md",