@birdapi/velinstyle 1.2.0 → 1.2.1

package/README.de.md

@@ -19,7 +19,7 @@ Ein Framework. Eine CLI. Ein Design System. Ein AI-fähiges Ökosystem.
 [![GitHub Stars](https://img.shields.io/github/stars/SkyliteDesign/velinstyle?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/stargazers)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square)](https://nodejs.org/)
 [![Browser](https://img.shields.io/badge/Browser-modern-0ea5e9?style=flat-square)](https://velinstyle.info/docs/getting-started/introduction.html)
-[![WCAG 2.2 AAA Support](https://img.shields.io/badge/WCAG_2.2-AAA_Support-16a34a?style=flat-square)](https://velinstyle.info/docs/a11y.html)
+[![WCAG 2.2 AAA Support](https://img.shields.io/badge/WCAG_2.2-AAA_Support-16a34a?style=flat-square)](https://velinstyle.info/docs/getting-started/accessibility.html)
 [![PRs Welcome](https://img.shields.io/badge/PRs-willkommen-2563eb?style=flat-square)](CONTRIBUTING.de.md)
 
 ```bash
@@ -32,12 +32,12 @@ npm i @birdapi/velinstyle
 
 ---
 
-VelinStyle ist ein **produktives CSS- + Web-Components-Framework** mit **WCAG-2.2-AAA-orientierten Defaults**, einer echten **CLI-Ship-Surface** und den ersten **Design-Intelligence- / AI-Foundation**-Systemen (Beta). Kein externes UI-Framework im Kern.
+VelinStyle ist ein **produktives CSS- + Web-Components-Framework** mit **WCAG-2.2-AAA-orientierten Defaults**, einer echten **CLI-Ship-Surface**, dem **Transparency Framework** (Kennzeichnung + Nachweis, Beta) und den ersten **Design-Intelligence- / AI-Foundation**-Systemen (Beta). Kein externes UI-Framework im Kern.
 
 **Passung heute:** Marketing-Landings, Docs-Shells, einfache Admin-Starter.  
 **Noch nicht:** alleiniger Primary-Stack für große Multipage-Shops + Enterprise-Admin ohne Custom-Arbeit.
 
-> **Release:** **1.2.0** (Core + Design Intelligence Foundation + Trust/Ship). VelinStyle **zertifiziert keine Anwendung** — siehe [A11y-Matrix](https://velinstyle.info/docs/a11y.html).
+> **Release:** **1.2.1** (Transparency Framework + Core + Design Intelligence Foundation + Trust/Ship). VelinStyle **zertifiziert keine Anwendung** — siehe [A11y-Matrix](https://velinstyle.info/docs/getting-started/accessibility.html).
 
 ---
 
@@ -64,7 +64,8 @@ Gegenüber **Bootstrap**: moderne Tokens/Layers, progressive WCs, CLI-Automation
 | 🎨 | **CSS-Framework** | OKLCH-Themes, Utilities, Komponenten, Lite-Preset |
 | 🧩 | **Web Components** | 40 kanonische Custom Elements; CSS allein reicht oft |
 | ⚡ | **Runtime** | Search, Motion, Highlight, Attributes, Tree-Shaking |
-| 🛠 | **CLI** | `create` · `serve` · `doctor` · `check` · `scan` · `review` · `skills` |
+| 🛠 | **CLI** | `create` · `serve` · `doctor` · `check` · `scan` · `review` · `skills` · `transparency` |
+| 🔎 | **Transparency** | Kennzeichnung + Nachweis (KI / Trust / Compliance / Metadaten) — Beta-Foundation |
 | 🧠 | **Design Intelligence** | Plan → Constraints → Registry → Review (Beta) |
 | 🤖 | **AI Skills** | 40 Skills, Packs, Bundles, Templates, Workflows (Beta) |
 | 📦 | **Registry** | Skills + Page/Section als maschinenlesbare Verträge |
@@ -77,17 +78,12 @@ Gegenüber **Bootstrap**: moderne Tokens/Layers, progressive WCs, CLI-Automation
 
 ---
 
-## Neu in 1.2
+## Neu in 1.2.1
 
-Kein reines CSS-Bump — ein **Foundation-Release**.
+- **Transparency Framework (Beta)** — `@birdapi/velinstyle/transparency`, Bridge `velin-transparency`, Claim-Taxonomie, CLI `transparency doctor|validate|report|export|migrate`
+- Baut auf der **1.2.0**-Foundation auf: Ship Surface, Design Intelligence, AI Skills, neue WC-Primitives
 
-- **Ship Surface** — `create`, `serve`, `doctor`, `check` (`--json` / `--sarif`)
-- **Design Intelligence (Beta)** — Prompt Engine, Review Engine, Knowledge-Graph-Seed, Constraints
-- **AI Foundation (Beta)** — Skill Engine, Workflows, reicheres Agent-Metadata
-- **Neue Primitives** — Calendar, File-Dropzone, editierbare Data-Table
-- **Trust Gates** — strengere Scan/Review-Regeln
-
-Details: [`RELEASE_NOTES_1.2.0.md`](RELEASE_NOTES_1.2.0.md) · Historie: [`CHANGELOG.md`](CHANGELOG.md)
+Details: [`CHANGELOG.md`](CHANGELOG.md) · 1.2.0-Überblick: [`RELEASE_NOTES_1.2.0.md`](RELEASE_NOTES_1.2.0.md)
 
 ---
 
@@ -100,8 +96,14 @@ yarn add @birdapi/velinstyle
 bun add @birdapi/velinstyle
 ```
 
-**CDN** (Version pinnen) — siehe [`README.md`](README.md#installation).  
-Nach Clone: `npm install && npm run build`.
+**CDN** (Version pinnen):
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle.min.css">
+<script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle-components.min.js"></script>
+```
+
+> Pin **`@1.2.1`** (oder `@latest` nach Publish). Nach Clone: `npm install && npm run build`.
 
 ---
 
@@ -121,8 +123,9 @@ Minimal-HTML und Import-Pfade: [`GETTING_STARTED.md`](GETTING_STARTED.md) · Sys
 | Befehl | Rolle |
 |--------|------|
 | `create` | Scaffolds (`landing` · `dashboard` · `docs` · `auth`) |
-| `check` | doctor + blueprints + scan + review |
+| `check` | doctor + blueprints + scan + review (+ Transparency-Scores) |
 | `scan` / `review` | Statische bzw. Design-Intelligence-Gates |
+| `transparency` | doctor · validate · report · export · migrate (Beta) |
 | `skills` / `workflow` | AI-Registry & Graphen (Beta) |
 | `wc api <tag>` | WC-API aus dem Source |
 | `meta` | Agent-Bundle + `llms.txt` |
@@ -133,7 +136,7 @@ Minimal-HTML und Import-Pfade: [`GETTING_STARTED.md`](GETTING_STARTED.md) · Sys
 
 **40 kanonische** Custom Elements (**42** Lazy-Loader inkl. Legacy-`*-wc`). Progressive Enhancement: HTML/CSS first, WC nur bei Verhalten.
 
-AAA-orientierte Token-Defaults, Fokus-Management, Reduced Motion, Scanner-Contracts — siehe [A11y-Matrix](https://velinstyle.info/docs/a11y.html).
+AAA-orientierte Token-Defaults, Fokus-Management, Reduced Motion, Scanner-Contracts — siehe [A11y-Matrix](https://velinstyle.info/docs/getting-started/accessibility.html).
 
 ---
 
@@ -142,8 +145,8 @@ AAA-orientierte Token-Defaults, Fokus-Management, Reduced Motion, Scanner-Contra
 | Status | Surfaces |
 |--------|----------|
 | **Stable** | CSS · Runtime · WC · CLI-Kern · Blueprints |
-| **Beta** | Review · Prompt · Knowledge Graph · AI Metadata · Constraints |
-| **Foundation** | AI Skills · Workflow Graphs · Registries |
+| **Beta** | Transparency Framework · Review · Prompt · Knowledge Graph · AI Metadata · Constraints |
+| **Foundation** | AI Skills · Workflow Graphs · Registries · Transparency pillars |
 | **Planned** | Studio · Utility Engine Generator |
 
 ---

package/README.md

@@ -19,7 +19,7 @@ One framework. One CLI. One design system. One AI-ready ecosystem.
 [![GitHub stars](https://img.shields.io/github/stars/SkyliteDesign/velinstyle?style=flat-square)](https://github.com/SkyliteDesign/velinstyle/stargazers)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square)](https://nodejs.org/)
 [![Browsers](https://img.shields.io/badge/Browsers-modern-0ea5e9?style=flat-square)](https://velinstyle.info/docs/getting-started/introduction.html)
-[![WCAG 2.2 AAA support](https://img.shields.io/badge/WCAG_2.2-AAA_support-16a34a?style=flat-square)](https://velinstyle.info/docs/a11y.html)
+[![WCAG 2.2 AAA support](https://img.shields.io/badge/WCAG_2.2-AAA_support-16a34a?style=flat-square)](https://velinstyle.info/docs/getting-started/accessibility.html)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-2563eb?style=flat-square)](CONTRIBUTING.md)
 
 ```bash
@@ -32,12 +32,12 @@ npm i @birdapi/velinstyle
 
 ---
 
-VelinStyle is a **production CSS + Web Components framework** with **WCAG 2.2 AAA-oriented defaults**, a real **CLI ship surface**, and the first **Design Intelligence / AI Foundation** systems (beta). No external UI framework in the core.
+VelinStyle is a **production CSS + Web Components framework** with **WCAG 2.2 AAA-oriented defaults**, a real **CLI ship surface**, the **Transparency Framework** (labeling + provenance, beta), and the first **Design Intelligence / AI Foundation** systems (beta). No external UI framework in the core.
 
 **Best fit today:** marketing landings, docs shells, simple admin starters.  
 **Not yet:** sole primary stack for large multipage shop + enterprise admin without custom work.
 
-> **Release:** **1.2.0** (Core + Design Intelligence Foundation + Trust/Ship). Using VelinStyle does **not** certify your app — see the [a11y matrix](https://velinstyle.info/docs/a11y.html).
+> **Release:** **1.2.1** (Transparency Framework + Core + Design Intelligence Foundation + Trust/Ship). Using VelinStyle does **not** certify your app — see the [a11y matrix](https://velinstyle.info/docs/getting-started/accessibility.html).
 
 ---
 
@@ -64,7 +64,8 @@ Compared to **Bootstrap**: modern tokens/layers, optional progressive WCs, CLI a
 | 🎨 | **CSS Framework** | OKLCH themes, utilities, components, lite preset for marketing budgets |
 | 🧩 | **Web Components** | 40 canonical custom elements; use CSS alone when you need no JS |
 | ⚡ | **Runtime** | Search, motion, highlight, attributes, `bootFromDOM` tree-shaking |
-| 🛠 | **CLI** | `create` · `serve` · `doctor` · `check` · `scan` · `review` · `skills` |
+| 🛠 | **CLI** | `create` · `serve` · `doctor` · `check` · `scan` · `review` · `skills` · `transparency` |
+| 🔎 | **Transparency** | Labeling + provenance (AI / trust / compliance / metadata) — beta foundation |
 | 🧠 | **Design Intelligence** | Plan → constraints → page/section registry → review (beta) |
 | 🤖 | **AI Skills** | 40 skills, packs, bundles, templates, workflow graphs (beta) |
 | 📦 | **Registry** | Skills + page/section registries as machine-readable contracts |
@@ -77,17 +78,12 @@ Compared to **Bootstrap**: modern tokens/layers, optional progressive WCs, CLI a
 
 ---
 
-## What's new in 1.2
+## What's new in 1.2.1
 
-Not a CSS bump — a **foundation release**.
+- **Transparency Framework (beta)** — `@birdapi/velinstyle/transparency`, `velin-transparency` bridge, claim taxonomy, CLI `transparency doctor|validate|report|export|migrate`
+- Builds on **1.2.0** foundation: ship surface, Design Intelligence, AI Skills, new WC primitives
 
-- **Ship surface** — `create landing|dashboard|docs|auth`, `serve`, `doctor`, `check` (`--json` / `--sarif`)
-- **Design Intelligence (beta)** — Prompt Engine (`plan`), Review Engine, knowledge graph seed, design constraints
-- **AI Foundation (beta)** — skill engine, workflows, richer agent metadata
-- **New primitives** — `<velin-calendar>`, `<velin-file-dropzone>`, editable `<velin-data-table>`
-- **Trust gates** — stricter scan/review so junk pages cannot fake green scores
-
-Details: [`RELEASE_NOTES_1.2.0.md`](RELEASE_NOTES_1.2.0.md) · full history: [`CHANGELOG.md`](CHANGELOG.md)
+Details: [`CHANGELOG.md`](CHANGELOG.md) · 1.2.0 overview: [`RELEASE_NOTES_1.2.0.md`](RELEASE_NOTES_1.2.0.md)
 
 ---
 
@@ -103,11 +99,11 @@ bun add @birdapi/velinstyle
 **CDN** (pin a version):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.0/dist/velinstyle.min.css">
-<script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.0/dist/velinstyle-components.min.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle.min.css">
+<script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle-components.min.js"></script>
 ```
 
-> Pin **`@1.2.0`** (or `@latest` after publish). Examples above match this package version.
+> Pin **`@1.2.1`** (or `@latest` after publish). Examples above match this package version.
 
 | Export | Use |
 |--------|-----|
@@ -127,8 +123,8 @@ After clone: `npm install && npm run build` — `dist/` is generated, not commit
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.0/dist/velinstyle.min.css">
-  <script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.0/dist/velinstyle-components.min.js"></script>
+  <link rel="stylesheet" href="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle.min.css">
+  <script type="module" src="https://unpkg.com/@birdapi/velinstyle@1.2.1/dist/velinstyle-components.min.js"></script>
 </head>
 <body class="velin-p-6">
   <button type="button" class="velin-btn velin-btn--primary">Ship it</button>
@@ -157,9 +153,10 @@ More: [`GETTING_STARTED.md`](GETTING_STARTED.md)
 | `build` | CSS build (`--preset lite` for marketing) |
 | `serve` | Static preview |
 | `doctor` | Install / path health |
-| `check` | doctor + blueprints + scan + review |
+| `check` | doctor + blueprints + scan + review (+ Transparency scores) |
 | `scan` | A11y / security / CSS / PII |
 | `review` | Design-intelligence gate (beta) |
+| `transparency` | doctor · validate · report · export · migrate (beta) |
 | `plan` | Prompt → plan JSON → render (beta) |
 | `skills` / `workflow` | AI skill registry & graphs (beta) |
 | `meta` | Agent bundle + `llms.txt` |
@@ -167,6 +164,7 @@ More: [`GETTING_STARTED.md`](GETTING_STARTED.md)
 
 ```bash
 npx @birdapi/velinstyle check . --profile marketing
+npx @birdapi/velinstyle transparency doctor . --policy examples/transparency.policy.json
 npx @birdapi/velinstyle wc api velin-toast
 ```
 
@@ -204,7 +202,7 @@ Accessibility is a **default**, not a plugin.
 - `prefers-reduced-motion` gating
 - Component a11y contracts + scanner rules
 
-Docs: [a11y matrix](https://velinstyle.info/docs/a11y.html) · AAA marketing language: see `VELINSTYLE_2030.md` (strategy ADRs are local-only)
+Docs: [a11y matrix](https://velinstyle.info/docs/getting-started/accessibility.html) · AAA marketing language: see `VELINSTYLE_2030.md` (strategy ADRs are local-only)
 
 ---
 
@@ -222,7 +220,8 @@ Docs: [a11y matrix](https://velinstyle.info/docs/a11y.html) · AAA marketing lan
 | CLI ship surface | [`docs/guides/cli-ship-surface.md`](docs/guides/cli-ship-surface.md) | create / check / wc |
 | AI Skills | [`docs/guides/ai-skills.md`](docs/guides/ai-skills.md) | Skills / workflows |
 | Product site | [velinstyle.info/docs](https://velinstyle.info/docs/getting-started/introduction.html) | Guides, demos, reference |
-| Upgrade | [`UPGRADING.md`](UPGRADING.md) | 1.1 → 1.2 |
+| Transparency | [Site guide](https://velinstyle.info/docs/guides/transparency.html) · `@birdapi/velinstyle/transparency` | Labeling + provenance |
+| Upgrade | [`UPGRADING.md`](UPGRADING.md) | 1.2.0 → 1.2.1 · 1.1 → 1.2 |
 | North star | [`VELINSTYLE_2030.md`](VELINSTYLE_2030.md) | Long-term vision |
 
 ---
@@ -233,7 +232,7 @@ Docs: [a11y matrix](https://velinstyle.info/docs/a11y.html) · AAA marketing lan
 velinstyle/
 ├── src/                 # CSS source (tokens, base, components, utilities)
 ├── components/          # Web Components (JS)
-├── core/                # Runtime: search, motion, highlight, attributes, meta
+├── core/                # Runtime: search, motion, highlight, attributes, meta, transparency
 ├── cli/                 # velinstyle binary
 ├── packages/            # React wrappers, skill-engine, skills registry
 ├── schemas/             # Design Intelligence + skill contracts
@@ -259,8 +258,8 @@ Humans own product intent. The framework ships reliable CSS and components. Desi
 | Status | Surfaces |
 |--------|----------|
 | **Stable** | CSS · Utilities · Runtime · Web Components · CLI core · Blueprints |
-| **Beta** | Review Engine · Prompt Engine · Knowledge Graph · AI Metadata · Design Constraints |
-| **Foundation** | AI Skills · Workflow Graphs · Registries |
+| **Beta** | Transparency Framework · Review Engine · Prompt Engine · Knowledge Graph · AI Metadata · Design Constraints |
+| **Foundation** | AI Skills · Workflow Graphs · Registries · Transparency pillars |
 | **Planned** | Studio · Utility Engine Generator |
 
 ---
@@ -274,7 +273,7 @@ Humans own product intent. The framework ships reliable CSS and components. Desi
 | A11y defaults | Partial | DIY | **AAA-capable tokens** |
 | Dark mode | Manual | `dark:` everywhere | **Token swap** |
 | Build required | No | Usually | **CDN optional** |
-| Design / AI gates | — | — | **plan · review · skills** |
+| Design / AI gates | — | — | **plan · review · skills · transparency** |
 
 ---
 

package/cli/cli-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.2.1",
   "commands": [
     {
       "name": "init",

package/cli/docgen/extract-attributes.js

@@ -30,6 +30,8 @@ const ATTRIBUTE_DOCS = {
   'velin-code': 'Code block with copy button and VelinHighlight syntax colors (use `language` or `velin-code="js"`).',
   'velin-quote': 'Styled blockquote.',
   'velin-highlight': 'Inline text mark (not syntax highlighting — use `velin-code` or `velinSyntax`).',
+  'velin-transparency': 'Velin Transparency Framework host — attaches disclosure + provenance mark (Renderer).',
+  'velin-disclosure': 'Alias for `velin-transparency`.',
 };
 
 /** Value | Meaning | Bridges to */

package/cli/index.js

@@ -45,6 +45,7 @@ const LAYER_FILES = {
     'components/timeline.css', 'components/stepper.css', 'components/stat.css',
     'components/drawer.css', 'components/input-group.css', 'components/form-validation.css', 'components/collapse.css',
     'components/calendar-dropzone.css',
+    'components/transparency.css',
   ],
   utilities: [
     'utilities/color.css', 'utilities/spacing.css', 'utilities/display.css',
@@ -101,7 +102,8 @@ function help() {
     velinstyle create <kind> [dir]  Scaffold: landing|dashboard|docs|auth
     velinstyle serve [dir]          Static preview server (default port 4173)
     velinstyle doctor               Check dist, icons, config, Windows ESM paths
-    velinstyle check [path]         doctor + blueprint --strict + scan + review
+    velinstyle transparency <sub>   Transparency Framework: doctor|validate|report|export|migrate
+    velinstyle check [path]         doctor + blueprint --strict + scan + review + transparency
     velinstyle scaffold "<prompt>"  Plan-first page HTML or recipe fragment
     velinstyle plan "<prompt>"      Emit page plan JSON (no HTML)
     velinstyle review [file|html]   Design / a11y / SEO / conversion review gate
@@ -146,10 +148,18 @@ function help() {
     velinstyle scaffold list-intents  Show recipe intent keywords
     velinstyle scaffold "<prompt>" -o out.html [--json]
 
-  ${C.bold('Plan / Review (1.2.0):')}
+  ${C.bold('Plan / Review (1.2.x):')}
     velinstyle plan "<prompt>" [--json] [-o plan.json]
     velinstyle review <file.html> [--json] [--prompt "..."]
 
+  ${C.bold('Transparency (1.2.1):')}
+    velinstyle transparency doctor [path|file] [--policy file] [--json]
+    velinstyle transparency validate [path|file] [--policy file] [--json]
+    velinstyle transparency report [path|file] [--out dir] [--policy file]
+    velinstyle transparency export [path|file] [--format json|json-ld|csv|html] [-o file]
+    velinstyle transparency migrate [path|file] [--apply] [--write] [--policy file]
+    Alias: transparency scan → doctor
+
   ${C.bold('Layout (0.8.0):')}
     velinstyle layout audit [path]    Report flex/grid/responsive issues
     velinstyle layout suggest [path]  Audit with fix suggestions
@@ -1123,6 +1133,20 @@ async function checkCmd() {
     steps.push({ step: 'review', ok: true, skipped: true });
   }
 
+  if (!quiet) console.log(C.bold('\n── transparency ──'));
+  try {
+    const { transparencyCheckStep } = await import('./transparency.js');
+    const tx = await transparencyCheckStep(htmlFile || target, { quiet, C });
+    if (!tx.ok && !tx.skipped) failed += 1;
+    if (!quiet && tx.scores) {
+      console.log(`Transparency ${tx.scores.transparency}% · AI ${tx.scores.ai}% · Trust ${tx.scores.trust}% · Provenance ${tx.scores.provenance}%`);
+    }
+    steps.push({ step: 'transparency', ok: tx.ok || !!tx.skipped, scores: tx.scores, skipped: tx.skipped });
+  } catch (err) {
+    if (!quiet) console.log(C.yellow(`transparency skipped: ${err.message}`));
+    steps.push({ step: 'transparency', ok: true, skipped: true, error: String(err.message || err) });
+  }
+
   const payload = {
     ok: failed === 0,
     failedSteps: failed,
@@ -1181,7 +1205,7 @@ async function checkCmd() {
 function suggestCommand(unknown) {
   const names = [
     'init', 'build', 'themes', 'add', 'icons', 'blueprint', 'create', 'serve', 'doctor', 'check',
-    'validate', 'tokens', 'scan', 'prefix', 'scaffold', 'plan', 'review', 'layout', 'perf',
+    'validate', 'tokens', 'scan', 'prefix', 'scaffold', 'plan', 'review', 'transparency', 'layout', 'perf',
     'docs', 'documentation', 'meta', 'search', 'skills', 'workflow', 'wc',
   ];
   const q = String(unknown || '').toLowerCase();
@@ -1244,6 +1268,11 @@ switch (resolvedCommand) {
   case 'scaffold': await scaffoldCmd(); break;
   case 'plan': await planCmd(); break;
   case 'review': await reviewCmd(); break;
+  case 'transparency': {
+    const { transparencyCmd } = await import('./transparency.js');
+    await transparencyCmd(args.slice(1), { C, getArg, hasFlag });
+    break;
+  }
   case 'layout': await layoutCmd(); break;
   case 'perf': await perfCmd(); break;
   case 'docs': await docsCmd(); break;

package/cli/transparency.js

@@ -0,0 +1,221 @@
+/**
+ * CLI: velinstyle transparency doctor|validate|report|export|migrate|scan
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { join, resolve, extname, basename } from 'path';
+import {
+  createTransparencyEngine,
+  normalizePolicy,
+} from '../core/transparency/index.js';
+
+function loadPolicy(policyPath) {
+  if (!policyPath) return normalizePolicy({});
+  const abs = resolve(policyPath);
+  if (!existsSync(abs)) throw new Error(`Policy not found: ${abs}`);
+  return normalizePolicy(JSON.parse(readFileSync(abs, 'utf-8')));
+}
+
+function collectHtmlFiles(target) {
+  const abs = resolve(target || '.');
+  if (!existsSync(abs)) throw new Error(`Path not found: ${abs}`);
+  const st = statSync(abs);
+  if (st.isFile()) return [abs];
+  const out = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      if (name === 'node_modules' || name === '.git' || name === 'dist') continue;
+      const p = join(dir, name);
+      const s = statSync(p);
+      if (s.isDirectory()) walk(p);
+      else if (/\.html?$/i.test(name)) out.push(p);
+    }
+  };
+  walk(abs);
+  return out;
+}
+
+function printScores(scores, C) {
+  if (!scores) return;
+  console.log(C.bold('\nScores'));
+  for (const [k, v] of Object.entries(scores)) {
+    console.log(`  ${k.padEnd(14)} ${v}%`);
+  }
+}
+
+/**
+ * @param {string[]} args process.argv slice after "transparency"
+ * @param {{ C: object, getArg: Function, hasFlag: Function }} util
+ */
+export async function transparencyCmd(args, util) {
+  const { C, getArg, hasFlag } = util;
+  const sub = args[0] || 'doctor';
+  const rest = args.slice(1);
+  const target = rest.find((a) => !a.startsWith('-')) || '.';
+  const policyPath = getArg('--policy');
+  const policy = loadPolicy(policyPath);
+  const asJson = hasFlag('--json');
+  const engine = createTransparencyEngine({ policy });
+
+  if (sub === 'scan') {
+    return runDoctor(target, engine, { asJson, C });
+  }
+  if (sub === 'doctor') {
+    return runDoctor(target, engine, { asJson, C });
+  }
+  if (sub === 'validate') {
+    return runValidate(target, engine, { asJson, C });
+  }
+  if (sub === 'report') {
+    return runReport(target, engine, { C, getArg });
+  }
+  if (sub === 'export') {
+    return runExport(target, engine, { C, getArg });
+  }
+  if (sub === 'migrate') {
+    return runMigrate(target, engine, { C, hasFlag, getArg });
+  }
+  if (sub === 'suggest') {
+    return runMigrate(target, engine, { C, hasFlag, getArg, forceDry: true });
+  }
+  if (sub === 'apply') {
+    return runMigrate(target, engine, { C, hasFlag, getArg, forceApply: true });
+  }
+
+  console.log(`Unknown transparency subcommand: ${sub}
+Usage:
+  velinstyle transparency doctor|validate|report|export|migrate|scan [path]
+`);
+  process.exitCode = 1;
+}
+
+async function runDoctor(target, engine, { asJson, C }) {
+  const files = collectHtmlFiles(target);
+  if (!files.length) {
+    console.log(C.yellow('No HTML files found.'));
+    process.exitCode = 1;
+    return;
+  }
+  const reports = [];
+  let failed = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const report = await engine.doctor(html, { file });
+    reports.push(report);
+    if (!report.ok) failed += 1;
+    if (!asJson) {
+      console.log(C.bold(`\n── ${basename(file)} ──`));
+      console.log(report.ok ? C.green('PASS') : C.red('FAIL'));
+      console.log(`disclosures=${report.summary.disclosures} errors=${report.summary.errors} warnings=${report.summary.warnings}`);
+      printScores(report.scores, C);
+      for (const f of report.findings.slice(0, 40)) {
+        const color = f.severity === 'error' ? C.red : f.severity === 'warning' ? C.yellow : C.dim;
+        console.log(color(`  [${f.severity}] ${f.code}: ${f.message}`));
+      }
+      if (report.findings.length > 40) console.log(C.dim(`  … ${report.findings.length - 40} more`));
+    }
+  }
+  if (asJson) {
+    console.log(JSON.stringify(files.length === 1 ? reports[0] : { reports }, null, 2));
+  } else {
+    console.log(failed ? C.red(`\ntransparency doctor: ${failed} file(s) failed`) : C.green('\ntransparency doctor: ok'));
+  }
+  if (failed) process.exitCode = 1;
+  return reports;
+}
+
+async function runValidate(target, engine, { asJson, C }) {
+  const files = collectHtmlFiles(target);
+  const all = [];
+  let failed = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const result = await engine.validate(html, { file });
+    all.push({ file, ...result });
+    if (!result.ok) failed += 1;
+    if (!asJson) {
+      console.log(`${basename(file)}: ${result.ok ? C.green('valid') : C.red('invalid')} (${result.findings.length} findings)`);
+    }
+  }
+  if (asJson) console.log(JSON.stringify(all, null, 2));
+  if (failed) process.exitCode = 1;
+}
+
+async function runReport(target, engine, { C, getArg }) {
+  const outDir = resolve(getArg('--out') || 'transparency-report');
+  mkdirSync(outDir, { recursive: true });
+  const files = collectHtmlFiles(target);
+  const combined = { schema: 'velinstyle.transparency.report.bundle', version: 1, files: [] };
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const artifacts = await engine.report(html, { file, title: `Transparency — ${basename(file)}` });
+    const base = basename(file, extname(file));
+    writeFileSync(join(outDir, `${base}.report.json`), JSON.stringify(artifacts.json, null, 2));
+    writeFileSync(join(outDir, `${base}.report.sarif`), JSON.stringify(artifacts.sarif, null, 2));
+    writeFileSync(join(outDir, `${base}.report.html`), artifacts.html);
+    combined.files.push({ file, scores: artifacts.json.scores, ok: artifacts.json.ok });
+  }
+  writeFileSync(join(outDir, 'index.json'), JSON.stringify(combined, null, 2));
+  console.log(C.green(`Wrote transparency reports to ${outDir}`));
+}
+
+async function runExport(target, engine, { C, getArg }) {
+  const format = getArg('--format') || 'json';
+  const out = getArg('--output') || getArg('-o');
+  const files = collectHtmlFiles(target);
+  const fresh = createTransparencyEngine({ policy: engine.policy });
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const { records } = await createTransparencyEngine({ policy: engine.policy }).ingest(html, { file });
+    for (const r of records) fresh.registry.register(r);
+  }
+  const body = fresh.export(format);
+  if (out) {
+    writeFileSync(resolve(out), body);
+    console.log(C.green(`Exported ${format} → ${out}`));
+  } else {
+    console.log(body);
+  }
+}
+
+async function runMigrate(target, engine, { C, hasFlag, getArg, forceDry, forceApply }) {
+  const apply = forceApply || hasFlag('--apply') || hasFlag('--write');
+  const dryRun = forceDry || (!apply);
+  const files = collectHtmlFiles(target);
+  let total = 0;
+  for (const file of files) {
+    const html = readFileSync(file, 'utf-8');
+    const result = await engine.migrate(html, { file, apply: apply && !dryRun, dryRun });
+    total += result.suggestions.length;
+    console.log(C.bold(`\n── ${basename(file)} ──`));
+    console.log(`${result.suggestions.length} suggestion(s)${apply && !dryRun ? `, applied ${result.applied}` : ' (dry-run)'}`);
+    for (const s of result.suggestions.slice(0, 30)) {
+      console.log(C.dim(`  • ${s.id || s.field || s.kind}: ${s.reason}`));
+    }
+    if (apply && !dryRun && result.applied) {
+      writeFileSync(file, result.html);
+      console.log(C.green(`  wrote ${file}`));
+    }
+  }
+  if (!total) console.log(C.green('\nNo migration suggestions.'));
+}
+
+/**
+ * Lightweight doctor for velinstyle check integration.
+ */
+export async function transparencyCheckStep(path, { policyPath, quiet, C } = {}) {
+  const policy = loadPolicy(policyPath);
+  const engine = createTransparencyEngine({ policy });
+  const files = collectHtmlFiles(path);
+  if (!files.length) return { ok: true, skipped: true, scores: null };
+  let failed = 0;
+  let lastScores = null;
+  for (const file of files.slice(0, 20)) {
+    const report = await engine.doctor(readFileSync(file, 'utf-8'), { file });
+    lastScores = report.scores;
+    if (!report.ok) failed += 1;
+    if (!quiet) {
+      console.log(`  ${basename(file)}: transparency ${report.scores?.transparency ?? '—'}% (${report.summary.errors} errors)`);
+    }
+  }
+  return { ok: failed === 0, failed, scores: lastScores };
+}

package/core/a11y/component-contracts.json

@@ -1,6 +1,6 @@
 {
   "wcagLevel": "AAA",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "components": {
     "velin-accordion": {
       "status": "pass",

package/core/attributes/registry.js

@@ -226,6 +226,20 @@ function registerBuiltins() {
     },
   });
 
+  registerAttribute('velin-transparency', {
+    async enhance(el) {
+      const { attach } = await import('../transparency/attach.js');
+      attach(el);
+    },
+  });
+  registerAttribute('velin-disclosure', {
+    async enhance(el) {
+      const { attach } = await import('../transparency/attach.js');
+      if (!el.hasAttribute('velin-transparency')) el.setAttribute('velin-transparency', '');
+      attach(el);
+    },
+  });
+
   for (const motion of ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover', 'velin-stagger', 'velin-scroll']) {
     registerAttribute(motion, { enhance() {} });
   }

package/core/meta/schema.js

@@ -48,4 +48,14 @@ export const AGENT_CONVENTIONS = [
   'Honor skill status, confidence, compatibility, and onlyIf predicates when automating.',
   'Do not put secrets, API keys, or raw emails in velin-meta or page meta.',
   'Resolve doc links against docs root (/docs/), not the current page folder.',
+  'Prefer Velin Transparency Framework (velin-transparency + provenance) for AI/trust/compliance labeling; run `velinstyle transparency doctor`.',
 ];
+
+/**
+ * Optional page-level transparency block for Velin Meta.
+ * @typedef {Object} VelinPageTransparency
+ * @property {object} [policy]
+ * @property {object[]} [disclosures]
+ * @property {object[]} [items]
+ */
+