@tidyfactor/doc 1.3.0 → 1.9.0

package/manifest.json

@@ -0,0 +1,216 @@
+{
+  "manifest_schema_version": "1.1.0",
+  "skill_id": "tidyfactor-doc",
+  "skill_root_anchor": "self",
+  "tools": [
+    {
+      "name": "audit_docs",
+      "description": "Audits documentation files under /docs, root README.md, and CHANGELOG.md for sensitive data leaks, banned absolute URLs, relative link integrity, and Keep a Changelog compliance.",
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/audit_docs.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {target_path} {flags}",
+        "args": [
+          {
+            "name": "target",
+            "type": "path",
+            "required": false,
+            "default": "docs",
+            "description": "Directory or markdown file path to audit"
+          },
+          {
+            "name": "json",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--json",
+            "description": "Output structured JSON report"
+          }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout"
+      },
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["generate", "site", "vitepress", "mkdocs", "docsify", "audit", "adr"]
+    },
+    {
+      "name": "clean_orphaned_assets",
+      "description": "Scans markdown files for image references, identifies unreferenced orphan assets in assets/, detects duplicate assets via SHA-256 hashing, and evaluates WebP compression savings.",
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/clean_orphaned_assets.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {repo_root} {flags}",
+        "args": [
+          {
+            "name": "repo_root",
+            "type": "path",
+            "required": false,
+            "default": ".",
+            "description": "Root directory of repository or skill"
+          },
+          {
+            "name": "assets_dir",
+            "type": "string",
+            "required": false,
+            "default": "assets",
+            "flag": "--assets-dir",
+            "description": "Relative path to assets folder"
+          },
+          {
+            "name": "delete_orphans",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--delete-orphans",
+            "description": "Delete unreferenced assets on disk"
+          },
+          {
+            "name": "json",
+            "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--json",
+            "description": "Output pure JSON report"
+          }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout"
+      },
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["audit", "site"]
+    }
+  ],
+  "decision_gates": [
+    {
+      "command": "brief",
+      "aliases": ["init", "debate"],
+      "description": "Decision gate selecting documentation engine, target persona, hygiene policy, and extraction scope.",
+      "decisions": [
+        {
+          "key": "target_scope",
+          "description": "Scope of documentation generation (D1)",
+          "type": "enum",
+          "options": ["full_codebase", "api_surface_only", "internal_architecture", "end_user_docs"],
+          "default": "full_codebase",
+          "priority": 1,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "docs/.doc-manifest.json"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+          }
+        },
+        {
+          "key": "doc_engine",
+          "description": "Target documentation publishing engine (D2)",
+          "type": "enum",
+          "options": ["vitepress_ssg", "mkdocs_material", "docsify_spa", "static_markdown"],
+          "default": "vitepress_ssg",
+          "priority": 2,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "docs/.vitepress/config.mjs",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "mkdocs.yml",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "docs/index.html",
+              "track_staleness": true
+            },
+            {
+              "source": "brain_ki",
+              "ki_type": "project"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" },
+            "brain_ki": {
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "audience_persona",
+          "description": "Primary audience reading the documentation (D3)",
+          "type": "enum",
+          "options": ["bilingual_developer", "api_consumer", "internal_maintainer", "end_user"],
+          "default": "bilingual_developer",
+          "priority": 3,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "brand.yaml",
+              "yaml_path": "audience"
+            },
+            {
+              "source": "local_file",
+              "path": "brand.json",
+              "json_path": "$.audience"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+          }
+        },
+        {
+          "key": "hygiene_policy",
+          "description": "Security redaction and sensitive data leak policy (D4)",
+          "type": "enum",
+          "options": ["strict_zero_leak", "public_sdk_redaction", "internal_audit_permissive"],
+          "default": "strict_zero_leak",
+          "priority": 4,
+          "discovery": [
+            {
+              "source": "brain_ki",
+              "ki_type": "security"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+          }
+        },
+        {
+          "key": "collection_depth",
+          "description": "Extraction dimensions depth for codebase collection (D5)",
+          "type": "enum",
+          "options": ["full_5_dimensions", "signatures_and_types", "architecture_and_rationale"],
+          "default": "full_5_dimensions",
+          "priority": 5,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "docs/.doc-manifest.json"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.yaml" }
+          }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tidyfactor/doc",
-  "version": "1.3.0",
-  "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
+  "version": "1.9.0",
+  "description": "TidyFactor Doc — Code Documentation Builder, ADR Architect, Link Auditor & Triple-Engine Publishing Platform (VitePress, MkDocs Material & Docsify) for AI Coding Agents",
   "main": "SKILL.md",
   "bin": {
     "tidyfactor-doc": "bin/add-skill.js",
@@ -50,6 +50,8 @@
     "assets",
     "bin",
     "brand.json",
+    "brand.yaml",
+    "manifest.json",
     "memory",
     "references",
     "scripts",

package/references/commands/adr.md

@@ -0,0 +1,25 @@
+# Command: adr
+
+Runtime entry point for "Generate Architectural Decision Record (ADR)" / "وثق قرار معماري" / "قم بتوليد سجل قرار معماري يشرح سبب اختيار التقنية [X]".
+
+## Context-Aware Prompts & Auto-Sensing
+
+1. **Auto-Sense Project Context**:
+   - Inspect package manifests (`composer.json`, `package.json`, `go.mod`, `Cargo.toml`) and framework configs.
+   - Identify active language, runtime version, and primary dependencies.
+   - Check `docs/adr/` to discover existing records and determine the next sequence number (`NNNN`).
+
+2. **Extract Decision Parameters**:
+   - Technology / Decision subject: e.g. `[VitePress]`, `[Medoo ORM]`, `[SQLite Storage]`, `[TailAdmin]`.
+   - If not provided in the user prompt, evaluate recent commit history (`git log -n 10`) or prompt the user via the native modal question tool.
+
+3. **Dispatch to Workflow**:
+   - Load `../workflows/generate-adr.md` — the MADR decision-making workflow.
+   - Load `../memory/adr-template.md` — the authoritative Markdown ADR schema.
+   - Load `../memory/tone-of-voice.md` — technical objectivity and zero fluff policy.
+   - Run the workflow.
+
+## Does NOT
+
+- Does not guess technical justifications: facts must trace to actual codebase constraints, benchmarks, or requirements.
+- Does not edit application code: ADRs are purely architectural documentation saved under `docs/adr/`.

package/references/commands/audit.md

@@ -0,0 +1,15 @@
+# Command: audit
+
+Runtime entry point for "audit docs quality" / "scan documentation hygiene" / "check broken doc links" / "verify changelog structure."
+
+## Dispatch steps
+
+1. Identify the target path to audit (defaults to `docs/` and root `README.md`, `CHANGELOG.md` if not explicitly specified).
+2. Load `../workflows/audit.md` — the step-by-step documentation quality audit sequence.
+3. Run the workflow.
+
+## Does NOT
+
+- Does not rewrite or author documentation files automatically without user review.
+- Does not publish documentation sites (that's `site` / `mkdocs` / `docsify` / `vitepress`).
+- Does not modify code or package configurations.

package/references/commands/brief.md

@@ -0,0 +1,16 @@
+# Command: brief
+
+Runtime entry point for establishing documentation context, running codebase interview, or conducting architectural debate ("brief", "interview", "debate", "استجوبني", "ناقشني في معمارية التوثيق").
+
+## Dispatch steps
+
+1. Load `../memory/decision-points.md` — the 5 core documentation decision dimensions (D1–D5), operational modes (Mode A / Mode B), and boolean skip conditions.
+2. Load `../workflows/brief.md` — the Context Delta Resolution, Dual Operational Mode execution, and persistence sequence.
+3. Run the workflow.
+
+## Does NOT
+
+- Does not author actual documentation content (no API entries, no guides, no READMEs). That's `generate`.
+- Does not scaffold `/docs` directory structure until baseline decisions are confirmed. That's `init`.
+- Does not run code-level AST parsing or git history log collection. That's `collect`.
+- Does not load `memory/stacks/*.md` or `memory/docsify-config.md` / `memory/mkdocs-config.md` — those are loaded only during generation or site compilation.

package/references/commands/generate.md

@@ -4,17 +4,18 @@ Runtime entry point for "write API docs" / "generate a README" / "add inline com
 
 ## Dispatch steps
 
-1. **Identify the doc type.** If not obvious from the request, ask:
-   > "Which one — API reference, README, inline code comments, or a technical guide (setup/architecture/workflow)?"
-2. **Identify the stack** (PHP / JS / TS / React / Vue / Next). If not obvious from the project, ask or detect from file extensions / config files (`composer.json`, `package.json` + `tsconfig.json`, framework config files).
+1. **Identify the doc type.** If not obvious from the request, ask or detect:
+   - API reference, README, CHANGELOG, inline code comments, or a technical guide (setup/architecture/workflow).
+2. **Identify the stack** (PHP / JS / TS / React / Vue / Next). If not obvious from the project, ask or detect from file extensions / config files (`composer.json`, `package.json` + `tsconfig.json`, framework config files). (Note: CHANGELOG and README are stack-agnostic).
 3. Load the matching workflow — exactly one:
    - API reference → `../workflows/generate-api.md`
    - README → `../workflows/generate-readme.md`
+   - CHANGELOG → `../workflows/generate-changelog.md`
    - Inline comments → `../workflows/generate-inline.md`
    - Guide → `../workflows/generate-guide.md`
-4. Load `../memory/doc-templates.md`.
-5. Load the matching stack file under `../memory/stacks/` — `php.md`, `js-ts.md`, or `react-vue-next.md`. Never load more than the stacks actually present in the target.
-6. Confirm `collect` has already run for this target (check for `docs/.collected/<target>.md`). If it hasn't, and the user hasn't supplied equivalent detail inline, stop and say so — do not generate from assumption. See constraint 2 in `SKILL.md`.
+4. Load `../memory/doc-templates.md` (and `../memory/changelog-rules.md` if generating a CHANGELOG).
+5. Load the matching stack file under `../memory/stacks/` — `php.md`, `js-ts.md`, or `react-vue-next.md` (if stack-dependent). Never load more than the stacks actually present in the target.
+6. For code/API docs, confirm `collect` has already run for this target (check for `docs/.collected/<target>.md`). For CHANGELOG, read git commit history (`git log`) and current `package.json` / version configs. If required detail is missing, stop and say so — do not generate from assumption. See constraint 2 in `SKILL.md`.
 7. Run the loaded workflow.
 
 ## Does NOT

package/references/commands/site.md

@@ -1,23 +1,25 @@
-# Command: site
-
-Runtime entry point for "turn /docs into a doc site" / "publish documentation portal" / "set up documentation site".
-
-## Dispatch steps
-
-1. Load `../memory/site-engines.md` — comparison between MkDocs Material and Docsify.
-2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold).
-3. **Interactive Engine Selection:**
-   - Detect if Python is available via `python --version 2>&1`.
-   - If the user explicitly requested a specific engine (e.g., "use mkdocs" or "use docsify"), route directly:
-     - "mkdocs" → Dispatch `references/commands/mkdocs.md`.
-     - "docsify" → Dispatch `references/commands/docsify.md`.
-   - If no engine was specified:
-     - Present the two options to the user with the summary from `memory/site-engines.md`:
-       - **Option 1: MkDocs Material (Recommended for Production)**: Pre-compiled static HTML, 100/100 Core Web Vitals, bilingual (Arabic RTL + English LTR) parallel builds, offline search indexing, and Neo-Brutalist styling. Requires Python locally for building.
-       - **Option 2: Docsify (Zero-Build Lightweight SPA)**: Client-side SPA, zero build step, single `index.html` + `_sidebar.md` over CDN. Recommended when Python is not available or for internal repo prototyping.
-     - Prompt the user to pick their preference or proceed with the recommended engine based on detected toolchain.
-4. Execute the chosen workflow (`workflows/mkdocs.md` or `workflows/docsify.md`).
-
-## Does NOT
-
-- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`.
+# Command: site
+
+Runtime entry point for "turn /docs into a doc site" / "publish documentation portal" / "set up documentation site".
+
+## Dispatch steps
+
+1. Load `../memory/site-engines.md` — comparison between VitePress, MkDocs Material, and Docsify.
+2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold).
+3. **Interactive Engine Selection:**
+   - Detect available runtimes: `node --version 2>&1` and `python --version 2>&1`.
+   - If the user explicitly requested a specific engine (e.g., "use vitepress", "use mkdocs", or "use docsify"), route directly:
+     - "vitepress" → Dispatch `references/commands/vitepress.md`.
+     - "mkdocs" → Dispatch `references/commands/mkdocs.md`.
+     - "docsify" → Dispatch `references/commands/docsify.md`.
+   - If no engine was specified:
+     - Present the options to the user with the summary from `memory/site-engines.md`:
+       - **Option 1: VitePress (Recommended for Modern Web, Monorepos & Luxury RTL)**: Vue 3 / Vite SSG, sub-second HMR, native multi-locale subdirectory routing (`/`, `/en/`, `/es/`), and bespoke luxury typography (`Alexandria` + `Cairo` + `JetBrains Mono`). Requires Node.js.
+       - **Option 2: MkDocs Material (Recommended for Python & Backend Services)**: Pre-compiled static HTML, 100/100 Core Web Vitals, parallel builds, offline search indexing, and Neo-Brutalist styling. Requires Python.
+       - **Option 3: Docsify (Zero-Build Lightweight SPA)**: Client-side SPA, zero build step, single `index.html` + `_sidebar.md` over CDN. Recommended when neither Node nor Python build workflows are available.
+     - Prompt the user to pick their preference or proceed with the recommended engine based on detected toolchain.
+4. Execute the chosen workflow (`workflows/vitepress.md`, `workflows/mkdocs.md`, or `workflows/docsify.md`).
+
+## Does NOT
+
+- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`.

package/references/commands/vitepress.md

@@ -0,0 +1,20 @@
+# Command: vitepress
+
+Runtime entry point for "Set up VitePress" / "build modern Vue-powered doc portal" / "vitepress".
+
+## Dispatch steps
+
+1. Load `../memory/vitepress-config.md` — complete ESM configuration schema, luxury CSS custom tokens, and script presets.
+2. Confirm `/docs` has real content (at least one generated doc beyond the scaffold).
+3. Verify Node.js toolchain (`node --version` >= 18).
+4. Dispatch `../workflows/vitepress.md`.
+
+## Injects
+
+- `../workflows/vitepress.md`
+- `../memory/vitepress-config.md`
+
+## Does NOT
+
+- Does not author any new markdown content — it structures, configures, and publishes what's already in `/docs`.
+- Does not use external unverified CSS frameworks; relies strictly on custom luxury design tokens (`Alexandria` + `Cairo` + `JetBrains Mono` + RTL logical properties).

package/references/memory/20-brain-baas-integration.md

@@ -0,0 +1,83 @@
+# Brain BaaS & Sovereign Knowledge Base Integration
+
+<!-- last-verified: 2026-09-02 -->
+
+> **Tier**: Core Intelligence Layer Contract  
+> **Authority**: Sovereign Self-Hosted & Local Multi-Tenant Architecture  
+> **Protocol**: Model B (Fail-Open Sovereign Agent Protocol)
+
+---
+
+## 🏛️ Architectural Doctrine & Deployment Model
+
+TidyFactor is strictly the **Intelligence, Context & Operating Layer** for AI agents. `tidyfactor-doc` operates under **Model B (Sovereign Self-Hosted Architecture)**:
+
+1. **Zero Centralized Data Exposure**: Codebase documentation, API schemas, and technical architectures are never transmitted to a centralized multi-tenant cloud service.
+2. **Local Multi-Tenant Isolation**: Each client or project maintains an isolated local SQLite knowledge base (`data/tenants/{tenant_id}_brain.sqlite`) or filesystem cache (`~/.gemini/knowledge/projects/{project_id}/`).
+3. **Fail-Open Invariant**: Brain MCP integration is completely optional at runtime. If `tidyfactor-brain` MCP is unavailable or disabled, `tidyfactor-doc` executes directly via local filesystem AST parsing and markdown generation with **0ms latency penalty** and zero connection errors.
+
+```
+┌────────────────────────────────────────────────────────┐
+│               AI Coding Agent Session                  │
+│       (Google Antigravity, Claude Code, Cursor)       │
+└───────────────────────────┬────────────────────────────┘
+                            │
+              [1] Check Active Tool Manifest
+                            │
+         ┌──────────────────┴──────────────────┐
+         │                                     │
+   [Brain MCP Active]                 [Brain MCP Absent]
+         │                                     │
+  [2] search_knowledge_base()                  │
+  (Doc Tree, APIs, Routes)                     │
+         │                                     │
+   (Found?)                                    │
+   ├── YES ──► Ingest KI Context               │
+   └── NO  ──► Direct Codebase Scan ◄──────────┘ (0ms Fail-Open)
+                            │
+               [3] Execute Doc Workflow
+               (init / collect / generate / site)
+                            │
+               [4] Persist /docs/ Artifacts
+                            │
+              (Optional: --sync-brain)
+                            │
+             [5] extract_knowledge_item()
+```
+
+---
+
+## 📋 Documentation Knowledge Item (KI) Payload Schema
+
+When persisting documentation structures or API contracts to the Brain via `--sync-brain`, payload objects MUST conform to the standard KI schema:
+
+```json
+{
+  "title": "Documentation Architecture: [Project Name]",
+  "category": "technical_architecture",
+  "scope": "project",
+  "tags": ["documentation", "api-reference", "mkdocs", "docsify", "architecture"],
+  "content": "### Codebase Overview\n...",
+  "metadata": {
+    "skill": "tidyfactor-doc",
+    "version": "1.4.0",
+    "site_engine": "mkdocs|docsify|none",
+    "doc_root": "docs/",
+    "entry_point": "docs/index.md",
+    "sidebar_configured": true,
+    "api_endpoints_count": 14,
+    "stacks": ["php", "typescript", "python"],
+    "i18n_enabled": true
+  }
+}
+```
+
+---
+
+## ⚡ Fail-Open Context Resolution Flow
+
+Every documentation command (`init`, `collect`, `generate`, `site`) executes context resolution deterministically:
+
+1. **Local Filesystem Scan**: Inspect `docs/`, `mkdocs.yml`, `_sidebar.md`, and project manifest (`package.json`, `composer.json`, `pyproject.toml`).
+2. **Optional Brain MCP Query**: If `search_knowledge_base` is active, retrieve existing architecture KIs for cross-referencing.
+3. **Silent Bypass**: If no Brain tool exists, complete the documentation task directly without prompting the user about server status.

package/references/memory/adr-template.md

@@ -0,0 +1,84 @@
+<!-- last-verified: 2026-09-09 -->
+# Memory: adr-template
+
+Authoritative MADR (Markdown Architectural Decision Records) schema for capturing significant architectural choices.
+
+## 1. Single Record Shape (`docs/adr/NNNN-<slug>.md`)
+
+```markdown
+# ADR [NNNN]: [Short Title of Solved Problem and Decision]
+
+- **Status**: [Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXXX]
+- **Date**: YYYY-MM-DD
+- **Decision-Makers**: [Architect / Agent / Team]
+- **Technical Story / Issue**: [Issue # or Feature Link]
+
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form or using 2-3 sentences. What forces are at play, what constraints must be satisfied?]
+
+## Decision Drivers
+
+- [Driver 1, e.g. sub-second build times]
+- [Driver 2, e.g. strict RTL and Arabic typography support]
+- [Driver 3, e.g. zero external runtime dependencies]
+
+## Considered Options
+
+- **Option 1**: [Name of Option 1]
+- **Option 2**: [Name of Option 2]
+- **Option 3**: [Name of Option 3]
+
+## Pros and Cons of the Options
+
+### Option 1: [Name]
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+
+### Option 2: [Name]
+
+- Good, because [argument a]
+- Bad, because [argument b]
+- Bad, because [argument c]
+
+## Decision Outcome
+
+**Chosen Option**: "[Option 1]", because [justification: e.g. it resolves Driver 1 and 2 while maintaining Driver 3].
+
+### Positive Consequences
+
+- [e.g. 80% reduction in asset footprint]
+- [e.g. Unified documentation deployment without Node.js runtime]
+
+### Negative Consequences / Trade-offs
+
+- [e.g. Requires manual markdown authoring instead of automated GUI]
+- [Mitigation: Automated pre-commit linting and link auditing]
+
+## Pros and Cons Matrix
+
+| Option | Performance | RTL Support | Maintenance Overhead | Ecosystem Maturity |
+|---|---|---|---|---|
+| Option 1 | High | Native | Low | High |
+| Option 2 | Medium | Partial | High | Very High |
+
+## References & Links
+
+- [Official Documentation](https://example.com)
+- [Related PR / Commit](https://github.com/org/repo/pull/1)
+```
+
+## 2. ADR Master Index Shape (`docs/adr/README.md`)
+
+```markdown
+# Architectural Decision Records (ADRs)
+
+This directory documents all significant architectural and technical decisions made in this project.
+
+| Number | Date | Title | Status |
+|---|---|---|---|
+| [0001](./0001-record-architecture-decisions.md) | 2026-09-09 | Record Architecture Decisions | Accepted |
+| [0002](./0002-triple-engine-publishing.md) | 2026-09-09 | Triple-Engine Publishing Platform | Accepted |
+```

package/references/memory/changelog-rules.md

@@ -0,0 +1,58 @@
+<!-- last-verified: 2026-09-09 -->
+# Memory: changelog-rules
+
+Codified rules and governance standards for maintaining `CHANGELOG.md` as the Single Source of Truth (SSOT) across all software and skill repositories.
+
+## 1. Authoritative Standards
+
+1. **Keep a Changelog v1.1.0**:
+   - Humans read changelogs, machines read git logs. Changelogs are curated summaries of user-facing and architectural value, not raw commit dumps.
+   - Guiding principles:
+     - Group changes by version and release date.
+     - Group changes within a release by type.
+     - Newest release always appears at the top (reverse chronological).
+     - Each version must have a release date formatted as `YYYY-MM-DD`.
+
+2. **Semantic Versioning (SemVer 2.0.0)**:
+   - Given a version number `MAJOR.MINOR.PATCH`:
+     - **`MAJOR` (x.0.0)**: Incompatible API changes, breaking architectural shifts, or removed features.
+     - **`MINOR` (0.x.0)**: Backward-compatible new functionality, new commands, or new workflows.
+     - **`PATCH` (0.0.x)**: Backward-compatible bug fixes, link repairs, or documentation corrections.
+
+## 2. Standard Change Sections
+
+Always classify changes into one of these 6 standardized buckets:
+
+| Section | Icon | Purpose |
+|---|---|---|
+| `Added` | 🚀 | New features, commands, workflows, or platform engines |
+| `Changed` | 🔄 | Modifications in existing functionality, refactors, or UI polish |
+| `Deprecated` | ⚠️ | Soon-to-be removed features that remain functional for now |
+| `Removed` | 🗑️ | Features, endpoints, or deprecated code deleted in this release |
+| `Fixed` | 🐛 | Any bug fixes, broken link repairs, or error corrections |
+| `Security` | 🔒 | Vulnerability fixes, credential redactions, or auth hardening |
+
+## 3. Conventional Commit Mapping
+
+When parsing `git log`, automatically map commit prefixes to changelog sections:
+
+| Git Commit Prefix | Changelog Section | SemVer Impact |
+|---|---|---|
+| `feat:` / `feat(*):` | `Added` | MINOR |
+| `refactor:` / `style:` / `perf:` | `Changed` | MINOR or PATCH |
+| `deprecate:` | `Deprecated` | MINOR |
+| `remove:` / `drop:` | `Removed` | MAJOR (if breaking) or MINOR |
+| `fix:` / `bug:` / `patch:` | `Fixed` | PATCH |
+| `sec:` / `security:` | `Security` | PATCH or MINOR |
+| `BREAKING CHANGE:` / `feat!:` | Any (`Added`/`Changed`) with breaking note | MAJOR |
+| `docs:` / `chore:` / `test:` | `Changed` or `Fixed` (or omitted if purely internal) | PATCH |
+
+## 4. Invariants & Hygiene
+
+- **Zero Undocumented Drift**: No production code or skill modification may be released without a corresponding dated entry in `CHANGELOG.md`.
+- **Atomic Metadata Synchronization**: When updating `CHANGELOG.md`, update all corresponding metadata files synchronously:
+  - `package.json` (`"version": "x.y.z"`)
+  - `.tidyfactor` (`"version": "x.y.z"`)
+  - `brand.yaml` / `brand.json` (`"version": "x.y.z"`)
+  - `README.md` / `README.ar.md` (Title banners)
+- **Zero Sensitive Data**: Never leak internal server paths, local absolute paths (`file:///C:`), or real API keys in changelogs.