@tidyfactor/doc 1.3.0

package/references/memory/stacks/react-vue-next.md

@@ -0,0 +1,50 @@
+# Memory: stacks/react-vue-next
+
+Component-level documentation conventions, layered on top of `js-ts.md` (still use JSDoc/TSDoc block syntax — this file adds what's specific to components, pages, and routes).
+
+## React — props, not just function signature
+
+```tsx
+/**
+ * <one-line summary of what the component renders/does>
+ */
+interface ButtonProps {
+  /** Description of this prop. */
+  label: string;
+  /** Optional, defaults to 'primary'. */
+  variant?: 'primary' | 'secondary';
+  /** Called when clicked. */
+  onClick?: () => void;
+}
+```
+
+- Document props via the `interface`/`type` block (per-member comments), not a `@param` list on the component function — that's the idiomatic React pattern and what most tooling (Storybook, TypeDoc) expects.
+- Note default values from the actual destructured defaults or `defaultProps`, not assumed.
+
+## Vue — SFC `<script>` block comments + `defineProps`
+
+```vue
+<script setup lang="ts">
+/**
+ * <one-line summary>
+ */
+defineProps<{
+  /** Description. */
+  label: string;
+  /** Optional, defaults to 'primary'. */
+  variant?: 'primary' | 'secondary';
+}>();
+</script>
+```
+
+- For Options API components (no `<script setup>`), document each prop inside the `props: {}` object with a comment above it instead.
+- Emitted events (`defineEmits` / `this.$emit`) get documented the same way props do — name, payload type, when it fires (from code parsing + error-patterns findings if it's an error event).
+
+## Next.js — pages/routes get a route-level note, not just a component doc
+
+- For a page/route file, prepend a comment noting the route path, whether it's a Server or Client Component, and any `params`/`searchParams` it reads — this is route contract, not just component contract.
+- API routes (`route.ts`/`route.js` under `app/api/`, or `pages/api/`) are documented as API reference (`generate-api`, using `js-ts.md`'s function conventions for the handler), not as component docs.
+
+## What NOT to document
+
+- Purely presentational/internal sub-components not exported from the module's public entry point: skip the full prop-table treatment unless they're complex enough that the error-patterns or persona-tracing findings flagged them as maintainer-relevant.

package/references/workflows/collect.md

@@ -0,0 +1,25 @@
+# Workflow: collect
+
+One outcome: a structured findings file — `docs/.collected/<target>.md` — that `generate` can turn into any doc type without re-deriving facts from the codebase itself. `<target>` is the module, package, API surface, or component named by the request (or the whole project if none was named).
+
+## Steps
+
+Run all five collection dimensions from `memory/collection-sources.md` against the target. Skip a dimension only if it genuinely doesn't apply (e.g., no Git history available for an uploaded snapshot) — note the skip and why, don't silently omit it.
+
+1. **Code parsing.** Extract existing docblocks/comments, function/method/class signatures, exported types, and public surface area directly from source. Flag anything already documented inline so `generate` doesn't duplicate it.
+2. **Commit history.** Read `git log` and any available PR descriptions for the target's files. Pull out *why* behind non-obvious code — rationale, past bugs fixed, deliberate tradeoffs — not just *what* changed.
+3. **Runtime & environment.** Enumerate required environment variables, config files, software dependencies (with version constraints), and any stated hardware/resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens found in `.env` or config files—record only variable names, expected formats, and generic placeholder values.
+4. **User persona tracing.** Identify who actually reads docs for this target — API consumers, internal maintainers, end-users — and note which facts matter to which persona (an internal maintainer needs the "why"; an API consumer needs the contract).
+5. **Error patterns.** Collect how the code fails: thrown exceptions, error codes, logged failure messages, and how each is meant to be handled or surfaced. Scrub any sensitive runtime credentials or local workstation paths that appear inside logged messages.
+
+6. **Write the findings** to `docs/.collected/<target>.md` as plain structured notes under five headings matching the dimensions above — this is source material for `generate`, not a finished doc, so skip prose polish.
+7. **Update `docs/.doc-manifest.json`**: add `<target>` to the `collected` section with a timestamp.
+
+## Validation checklist
+
+- [ ] `docs/.collected/<target>.md` exists and has content (or an explicit "not applicable" note) under all five dimension headings
+- [ ] Every fact traces to something actually found in the code, history, config, or logs — nothing inferred or assumed
+- [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets are replaced with safe generic placeholders
+- [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist in findings; all paths are normalized to project-relative paths
+- [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`
+- [ ] Findings are organized by dimension, not pre-formatted as any particular doc type

package/references/workflows/docsify.md

@@ -0,0 +1,19 @@
+# Workflow: docsify
+
+One outcome: `/docs` is browsable as a Docsify site — an `index.html` entry point and an auto-generated `_sidebar.md`, wired per `memory/docsify-config.md`.
+
+## Steps
+
+1. **Write `docs/index.html`** using the template in `memory/docsify-config.md` — project name, theme, and the plugin list from that file. Do not hand-roll a different Docsify setup.
+2. **Generate `docs/_sidebar.md`** by walking the current `/docs` tree per `doc-tree.md`'s structure and listing every existing generated file (skip `.doc-manifest.json` and the `.collected/` folder — those aren't site content). Group by section (API, Guides, root docs) matching the folder structure.
+3. **Optionally write `docs/_coverpage.md`** if the user wants a landing/cover page — only if asked, per `docsify-config.md`'s note that the coverpage is opt-in, not default.
+4. **Report how to preview it** (local static server command from `docsify-config.md`) and note the deploy targets listed there (GitHub Pages / Netlify / Cloudflare Pages / cPanel static hosting) without picking one — that's the user's call.
+
+## Validation checklist
+
+- [ ] `docs/index.html` exists and matches the template/plugin list in `memory/docsify-config.md`
+- [ ] `docs/_sidebar.md` lists every current doc under `/docs`, correctly grouped, and excludes `.doc-manifest.json`/`.collected/`
+- [ ] All sidebar links use root-relative leading slashes (`/guides/...`, `/api/...`) and never point outside `/docs` (no `../` or `file:///` links)
+- [ ] No real secrets or sensitive server configurations are hardcoded into `docs/index.html` or navigation files
+- [ ] No new documentation *content* was authored by this workflow — only navigation/entry-point files
+- [ ] Preview instructions and deploy target options were reported, with no deploy target chosen unilaterally

package/references/workflows/generate-api.md

@@ -0,0 +1,21 @@
+# Workflow: generate-api
+
+One outcome: an API reference file under `docs/api/` for one target, built from `docs/.collected/<target>.md` and formatted per the matching `memory/stacks/*.md` file.
+
+## Steps
+
+1. **Load the findings** from `docs/.collected/<target>.md`. If it doesn't exist, stop — see constraint 2 in `SKILL.md`.
+2. **Pull the doc-type shape** from `memory/doc-templates.md` (API reference section) and the **comment/tag conventions** from the matching stack file — PHPDoc tags for PHP, JSDoc for JS, TSDoc for TS, or component prop-table conventions for React/Vue/Next.
+3. **Write `docs/api/<target>.md`**: for every public function/method/endpoint/component found in the findings, document signature, parameters (with types), return value, thrown errors (from the "error patterns" findings), and a short usage example. Prioritize facts an **API consumer** needs (per the persona-tracing findings) over internal rationale. Ensure code examples use dummy/placeholder tokens and endpoints, never real secrets.
+4. **Cross-link**: if the target has related targets already documented, add clean relative "See also" links between them (e.g. `[Other API](./other.md)`). Never use `file:///` or local drive paths.
+5. **Update `docs/.doc-manifest.json`**'s `generated` section with the new file and timestamp.
+
+## Validation checklist
+
+- [ ] `docs/api/<target>.md` exists and follows the API-reference shape in `memory/doc-templates.md`
+- [ ] Every documented signature matches what `collect` actually found — no invented parameters or return types
+- [ ] Comment/tag style matches the target's stack file exactly (no PHPDoc tags in a TS doc, etc.)
+- [ ] Zero sensitive data leaked (all auth tokens, secrets, private IPs replaced with generic placeholders)
+- [ ] All cross-references use clean relative markdown paths or web URLs; zero `file:///` or local absolute drive paths
+- [ ] Thrown/returned error conditions from the findings are represented
+- [ ] `docs/.doc-manifest.json` updated

package/references/workflows/generate-guide.md

@@ -0,0 +1,20 @@
+# Workflow: generate-guide
+
+One outcome: a single technical guide file under `docs/guides/`, built from `docs/.collected/<target>.md` and the guide shape in `memory/doc-templates.md`. One guide = one purpose (setup, architecture, or a specific workflow) — a request covering two purposes ("how to set up AND how deploys work") is two guides, run this workflow twice.
+
+## Steps
+
+1. **Identify the guide's single purpose** — setup/getting-started, architecture overview, or a specific operational workflow (e.g., "how releases work"). If the request bundles more than one, split it before continuing.
+2. **Load the findings** from `docs/.collected/<target>.md`. If it doesn't exist, stop — see constraint 2 in `SKILL.md`.
+3. **Pull the guide shape** from `memory/doc-templates.md` (guide section) for the identified purpose.
+4. **Write `docs/guides/<purpose-slug>.md`**, prioritizing facts for the persona that reads this kind of guide (per persona-tracing findings — usually an internal maintainer or a new contributor, not an external API consumer). Ensure all configuration code blocks, commands, IPs, and tokens use safe placeholders. Use clean relative links for cross-references.
+5. **Update `docs/.doc-manifest.json`**'s `generated` section.
+
+## Validation checklist
+
+- [ ] The guide covers exactly one purpose — no bundled setup+architecture+workflow content in one file
+- [ ] `docs/guides/<purpose-slug>.md` exists and follows the shape in `memory/doc-templates.md`
+- [ ] Every step/claim traces to the findings — nothing assumed
+- [ ] Zero sensitive data leaked: all server IPs, DB credentials, API keys, or private paths replaced with placeholders
+- [ ] All internal links are clean relative markdown links; no `file:///` or local drive paths
+- [ ] `docs/.doc-manifest.json` updated

package/references/workflows/generate-inline.md

@@ -0,0 +1,20 @@
+# Workflow: generate-inline
+
+One outcome: source files in the target with inline documentation comments added or brought up to date, per the matching stack file's conventions. This workflow edits source directly — it does not write anything under `/docs`.
+
+## Steps
+
+1. **Load the findings** from `docs/.collected/<target>.md`, specifically the code-parsing section (what's already documented) and the error-patterns section (what exceptions/failure modes need noting).
+2. **Load the comment convention** from the matching stack file — PHPDoc block format for PHP, JSDoc for JS, TSDoc for TS, component-comment conventions for React/Vue/Next.
+3. **For each undocumented (or stale-documented) public function/method/class/component in the target**, add or correct a doc comment: purpose, parameters, return value, thrown/handled errors. Leave already-correct existing comments untouched — this is additive/corrective, not a rewrite of the file.
+4. **Do not touch private/internal implementation details** that don't need a doc comment per the stack convention — inline documentation targets the public surface, not every line.
+5. **Update `docs/.doc-manifest.json`**'s `generated` section, listing the files touched (not a `/docs` file, but still tracked for audit purposes).
+
+## Validation checklist
+
+- [ ] Every added/updated comment follows the target stack's exact convention (tag names, block format)
+- [ ] No comment content is invented — parameters, return types, and error conditions match the actual code and the findings
+- [ ] Zero secrets, private passwords, internal IPs, or machine absolute paths added into docblocks/comments
+- [ ] Already-correct existing comments were left untouched
+- [ ] Only public surface area was documented, not every internal line
+- [ ] `docs/.doc-manifest.json`'s `generated` section lists the touched files

package/references/workflows/generate-readme.md

@@ -0,0 +1,20 @@
+# Workflow: generate-readme
+
+One outcome: a project-root `README.md`, built from `docs/.collected/<target>.md` (target = whole project) and the README shape in `memory/doc-templates.md`. This is the one exception to "everything generated lives under /docs" — README stays at the project root, per convention.
+
+## Steps
+
+1. **Load the findings** from `docs/.collected/<target>.md`. If it doesn't exist for the whole project, stop — see constraint 2 in `SKILL.md`.
+2. **Pull the README shape** from `memory/doc-templates.md`.
+3. **Write `README.md`** at the project root: project name/one-line description, install/setup steps (from the runtime & environment findings), usage example, required env vars (with safe placeholders, never real secrets), and a clean relative link to `./docs/README.md` or `docs/` for the full reference. Keep it scannable — this is an entry point, not the full documentation.
+4. **If a `README.md` already exists**, show a diff-style summary of what would change rather than overwriting silently, and confirm before replacing it.
+5. **Update `docs/.doc-manifest.json`**'s `generated` section.
+
+## Validation checklist
+
+- [ ] `README.md` exists at project root and follows the shape in `memory/doc-templates.md`
+- [ ] Every setup/env-var claim traces to the runtime & environment findings — nothing assumed
+- [ ] Zero real secrets, API keys, or passwords in environment variable tables or examples
+- [ ] Existing `README.md` content was never silently overwritten without confirmation
+- [ ] Links to `docs/` are clean relative links (`./docs/README.md`), never local absolute drive paths or `file:///` URLs
+- [ ] `docs/.doc-manifest.json` updated

package/references/workflows/init-docs.md

@@ -0,0 +1,18 @@
+# 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

package/references/workflows/mkdocs.md

@@ -0,0 +1,44 @@
+# Workflow: mkdocs
+
+One outcome: A fully compiled, statically hosted MkDocs Material documentation portal configured per `memory/mkdocs-config.md`.
+
+---
+
+## Steps
+
+1. **Verify Environment & Dependencies:**
+   - Run `python --version` and ensure Python is accessible.
+   - Write `requirements.txt` containing `mkdocs-material>=9.5` and `mkdocs-static-i18n>=1.2`.
+   - Install dependencies via `pip install -r requirements.txt` if not already installed.
+
+2. **Structure `/docs` Source Tree:**
+   - Ensure documentation markdown files live in `docs/` (e.g. `docs/index.md`, `docs/guides/`, `docs/api/`).
+   - If bilingual, ensure Arabic files use the `.ar.md` suffix (e.g., `docs/guides/topic.ar.md`).
+   - Strip any raw `<div align="center">` wrappers around Markdown headers so Python-Markdown parses them cleanly.
+
+3. **Generate Configuration (`mkdocs.yml`):**
+   - Write `mkdocs.yml` at the documentation root using the schema in `memory/mkdocs-config.md`.
+   - Configure site name, palette themes (`tidyfactor-light` and `tidyfactor-dark`), PyMdown extensions, and the `nav:` tree mirroring `/docs`.
+
+4. **Inject Luxury Styling & JS Enhancers:**
+   - Create `docs/stylesheets/extra.css` with Neo-Brutalist tokens, macOS terminal dots for code blocks, and Arabic font pairings (`El Messiri` + `Tajawal`).
+   - Create `docs/javascripts/extra.js` with the GitHub alert transformer and badge bar formatter.
+
+5. **Build & Validate:**
+   - Run `mkdocs build --strict` to ensure 0 warnings and 0 broken links.
+   - If hosting locally on Apache, inject `.htaccess` with transparent rewrite rules pointing to `site/`.
+
+6. **Report Deployment Instructions:**
+   - Report local preview command: `mkdocs serve` (runs at `http://127.0.0.1:8000`).
+   - Report production deploy rule: upload the generated contents of `site/` directly into the public server directory.
+
+---
+
+## Validation Checklist
+
+- [ ] `mkdocs.yml` exists with valid YAML syntax and complete `nav:` mapping
+- [ ] `docs/index.md` exists and contains no unparsed raw HTML header wrappers
+- [ ] `docs/stylesheets/extra.css` and `docs/javascripts/extra.js` are present
+- [ ] `mkdocs build` completes with **zero errors and zero broken links**
+- [ ] Language switcher functions properly between English and Arabic (if bilingual)
+- [ ] Clean relative links only — no workstation paths (`file:///C:/...`) or hardcoded secrets

package/tools/build-skill.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * build-skill.js — packages the distributable Claude Skill (.skill file)
+ * for TidyFactor Doc from the repo's single source of truth.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync, spawnSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const SKILL_NAME = "tidyfactor-doc";
+const DIST_DIR = path.join(ROOT, "dist");
+const STAGE_DIR = path.join(DIST_DIR, SKILL_NAME);
+
+const args = process.argv.slice(2);
+const outFlagIdx = args.indexOf("--out");
+const OUT_FILE =
+  outFlagIdx !== -1 && args[outFlagIdx + 1]
+    ? path.resolve(ROOT, args[outFlagIdx + 1])
+    : path.join(DIST_DIR, `${SKILL_NAME}.skill`);
+
+const ROOT_COPIES = [
+  "SKILL.md",
+  "references",
+  "tools",
+  "bin",
+  "brand.json",
+  ".tidyfactor",
+  "package.json",
+  "AGENTS.md",
+  "README.md",
+  "README.ar.md",
+  "README.fa.md",
+  "README.es.md",
+  "README.pt.md",
+  "README.zh.md",
+  "README.de.md",
+  "README.fr.md",
+  "LICENSE",
+  "CHANGELOG.md",
+];
+
+function log(msg) {
+  console.log(`[build-skill] ${msg}`);
+}
+
+function rmrf(p) {
+  if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+function copyRecursive(src, dest) {
+  if (!fs.existsSync(src)) {
+    log(`  ⚠ skipped (not found): ${path.relative(ROOT, src)}`);
+    return;
+  }
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function zipArchive(stagePath, outFile, cwdDir) {
+  log("zipping Claude skill archive...");
+  if (fs.existsSync(outFile)) fs.rmSync(outFile);
+
+  const stageBasename = path.basename(stagePath);
+
+  // 1. Try native `zip` command
+  try {
+    execFileSync("zip", ["-r", "-q", outFile, stageBasename], {
+      cwd: cwdDir,
+      stdio: "inherit",
+    });
+    return;
+  } catch (err) {
+    // fallback
+  }
+
+  // 2. Try Python built-in zipfile module
+  try {
+    const pythonCmd = process.platform === "win32" ? "python" : "python3";
+    execFileSync(pythonCmd, ["-m", "zipfile", "-c", outFile, stageBasename], {
+      cwd: cwdDir,
+      stdio: "inherit",
+    });
+    return;
+  } catch (pyErr) {
+    // fallback
+  }
+
+  // 3. Try PowerShell Compress-Archive
+  try {
+    const tmpZip = outFile.replace(/\.(skill|zip)$/, ".zip");
+    if (fs.existsSync(tmpZip)) fs.rmSync(tmpZip);
+    const result = spawnSync(
+      "powershell",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        `Compress-Archive -Path "${stagePath}" -DestinationPath "${tmpZip}" -Force`,
+      ],
+      { stdio: "inherit" }
+    );
+    if (result.status === 0) {
+      if (tmpZip !== outFile) {
+        fs.renameSync(tmpZip, outFile);
+      }
+      return;
+    }
+  } catch (winErr) {
+    // throw cumulative
+  }
+
+  throw new Error("Failed to create zip archive via zip, Python, or PowerShell.");
+}
+
+function main() {
+  log(`repo root: ${ROOT}`);
+  log("cleaning previous build...");
+  rmrf(STAGE_DIR);
+  fs.mkdirSync(STAGE_DIR, { recursive: true });
+
+  log("staging single-source-of-truth files from repo root...");
+  for (const name of ROOT_COPIES) {
+    const src = path.join(ROOT, name);
+    const dest = path.join(STAGE_DIR, name);
+    copyRecursive(src, dest);
+    log(`  + ${name}`);
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+  const versionedOutFile = path.join(DIST_DIR, `${SKILL_NAME}-v${pkg.version}.skill`);
+
+  fs.mkdirSync(path.dirname(OUT_FILE), { recursive: true });
+  zipArchive(STAGE_DIR, OUT_FILE, DIST_DIR);
+  fs.copyFileSync(OUT_FILE, versionedOutFile);
+
+  const sizeKb = (fs.statSync(OUT_FILE).size / 1024).toFixed(1);
+  log(`done → ${path.relative(ROOT, OUT_FILE)} (${sizeKb} KB)`);
+  log(`✓ Created versioned archive → ${path.relative(ROOT, versionedOutFile)}`);
+
+  // Auto-sync to Skills-LAB root if located inside Skills-LAB
+  const skillLabRoot = path.resolve(ROOT, "..");
+  const skillLabTarget = path.join(skillLabRoot, `${SKILL_NAME}.skill`);
+  const skillLabVersionedTarget = path.join(skillLabRoot, `${SKILL_NAME}-v${pkg.version}.skill`);
+  if (path.basename(skillLabRoot) === "Skills-LAB") {
+    fs.copyFileSync(OUT_FILE, skillLabTarget);
+    fs.copyFileSync(OUT_FILE, skillLabVersionedTarget);
+    log(`✓ Updated Skills-LAB root archives → ${SKILL_NAME}.skill & ${SKILL_NAME}-v${pkg.version}.skill`);
+  }
+}
+
+main();

package/tools/validate_skill.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+validate_skill.py — TidyFactor Doc Release & Integrity Validator.
+Checks:
+1. SemVer synchronization across package.json, .tidyfactor, brand.json, CHANGELOG.md.
+2. License consistency (Apache-2.0).
+3. Existence of all files referenced in SKILL.md.
+4. Validation checklists in all workflow files.
+5. Absence of machine-specific absolute paths.
+"""
+
+import sys
+import os
+import json
+import re
+from pathlib import Path
+
+# Ensure UTF-8 output on Windows terminal
+if sys.platform == "win32":
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+def main():
+    root = Path(__file__).resolve().parent.parent
+    errors = []
+    
+    print("=" * 60)
+    print("  RUNNING TIDYFACTOR DOC RELEASE VALIDATION")
+    print("=" * 60)
+    
+    # 1. SemVer Synchronization Check
+    print("\n[1] Checking SemVer synchronization across metadata...")
+    pkg_file = root / "package.json"
+    tf_file = root / ".tidyfactor"
+    brand_file = root / "brand.json"
+    cl_file = root / "CHANGELOG.md"
+    
+    pkg_ver = json.loads(pkg_file.read_text(encoding="utf-8")).get("version") if pkg_file.exists() else None
+    tf_ver = json.loads(tf_file.read_text(encoding="utf-8")).get("version") if tf_file.exists() else None
+    
+    brand_data = json.loads(brand_file.read_text(encoding="utf-8")) if brand_file.exists() else {}
+    brand_ver = brand_data.get("version") or brand_data.get("meta", {}).get("version")
+    
+    print(f"  package.json : {pkg_ver}")
+    print(f"  .tidyfactor  : {tf_ver}")
+    print(f"  brand.json   : {brand_ver}")
+    
+    if not (pkg_ver and tf_ver and brand_ver and pkg_ver == tf_ver == brand_ver):
+        errors.append(f"Version mismatch: package.json({pkg_ver}) vs .tidyfactor({tf_ver}) vs brand.json({brand_ver})")
+    else:
+        print(f"  [OK] Version {pkg_ver} synchronized across all JSON metadata.")
+        
+    if cl_file.exists():
+        cl_text = cl_file.read_text(encoding="utf-8")
+        if f"## [{pkg_ver}]" not in cl_text and f"[{pkg_ver}]" not in cl_text:
+            errors.append(f"CHANGELOG.md is missing release entry for version [{pkg_ver}].")
+        else:
+            print(f"  [OK] CHANGELOG.md contains release entry for [{pkg_ver}].")
+    else:
+        errors.append("Missing CHANGELOG.md.")
+        
+    # 2. License check
+    print("\n[2] Checking license consistency...")
+    license_file = root / "LICENSE"
+    if license_file.exists():
+        print("  [OK] LICENSE file exists (Apache-2.0).")
+    else:
+        errors.append("Missing LICENSE file.")
+        
+    # 3. Check referenced files in SKILL.md
+    print("\n[3] Checking SKILL.md referenced files exist on disk...")
+    skill_md = root / "SKILL.md"
+    if skill_md.exists():
+        content = skill_md.read_text(encoding="utf-8")
+        # filter out wildcards like generate-*.md
+        refs = re.findall(r'(?:references|memory|commands|workflows)/[a-zA-Z0-9_\-\./]+(?:\.md|\.json)?', content)
+        for ref in sorted(set(refs)):
+            if "*" in ref or ref.endswith("-"):
+                continue
+            target = root / ref
+            if not target.exists() and not (root / "references" / ref).exists():
+                if not (root / ref).is_dir() and not (root / "references" / ref).is_dir():
+                    errors.append(f"SKILL.md references non-existent file: {ref}")
+            else:
+                print(f"  [OK] Found {ref}")
+    else:
+        errors.append("Missing SKILL.md.")
+
+    # 4. Check workflow validation checklists
+    print("\n[4] Checking workflow checklists...")
+    wf_dir = root / "references" / "workflows"
+    if wf_dir.exists():
+        for wf in wf_dir.glob("*.md"):
+            txt = wf.read_text(encoding="utf-8").lower()
+            if "validation checklist" not in txt:
+                errors.append(f"Workflow {wf.name} missing '## Validation checklist'")
+            else:
+                print(f"  [OK] {wf.name} has Validation checklist.")
+
+    # 5. Audit for leaked machine paths
+    print("\n[5] Auditing for leaked machine-specific absolute paths...")
+    for ext in ["*.md", "*.json", "*.js", "*.py"]:
+        for file in root.rglob(ext):
+            if any(part in file.parts for part in [".git", "node_modules", "dist"]):
+                continue
+            text = file.read_text(encoding="utf-8", errors="ignore")
+            if re.search(r'[A-Za-z]:\\[Users|wamp64|Dev\-Studio]', text, re.IGNORECASE):
+                if file.name not in ["release_suite.py", "audit_all_skills.py"]:
+                    errors.append(f"Machine-specific absolute path found in: {file.relative_to(root)}")
+
+    print("\n" + "=" * 60)
+    if errors:
+        print(f"[FAIL] {len(errors)} validation error(s) found:")
+        for err in errors:
+            print(f"  - {err}")
+        print("=" * 60)
+        sys.exit(1)
+    else:
+        print("[SUCCESS] ALL SKILL INTEGRITY CHECKS PASSED!")
+        print("=" * 60)
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()