@joktec/skills 0.1.0

package/dist/windsurf/.windsurf/rules/joktec-framework-skill.md

@@ -0,0 +1,58 @@
+# JokTec Framework Skill
+
+Use when working in a consumer project that uses @joktec/* packages and the agent needs to choose the right JokTec package skill, understand package boundaries, wire modules, or avoid mixing app logic into reusable JokTec infrastructure.
+
+Start here when a task mentions JokTec generally, multiple `@joktec/*` packages, or a consumer app that needs framework wiring.
+
+## Select The Focused Skill
+
+- For `@joktec/core`, `@joktec/utils`, or `@joktec/cron`, use `joktec-common-skill`.
+- For `@joktec/mongo`, use `joktec-mongo-skill`.
+- For `@joktec/mysql`, use `joktec-mysql-skill`.
+- For Kafka, RabbitMQ, SQS, or Redcast, use `joktec-broker-skill`.
+- For cache, mail, notification, or storage adapters, use `joktec-adapter-skill`.
+- For Elastic, Arango, or BigQuery, use `joktec-database-extended-skill`.
+- For Firebase or GPT integrations, use `joktec-integration-skill`.
+- For HTTP, file, or alert utilities, use `joktec-tool-skill`.
+
+## Core Rules
+
+- Treat `joktec-framework` code, package README files, and agent docs as source-of-truth.
+- Keep consumer app business logic in the app; do not move it into `@joktec/*` packages.
+- Prefer config-driven module setup and `conId` when a package supports multiple clients.
+- Preserve NestJS module boundaries, dependency injection, lifecycle hooks, and exported package APIs.
+- Do not invent behavior for unfinished or missing packages.
+
+## Reference
+
+Read `references/framework-map.md` when the task needs package selection, dependency flow, or a quick map from requirement to package.
+
+## Bundled References
+
+### references/framework-map.md
+
+# JokTec Framework Map
+
+## Package Families
+
+- `@joktec/core`: bootstrap, config, logger, metrics, guards, base abstractions, transports, pagination, Bull.
+- `@joktec/utils`: low-level helpers, validators, conversion utilities.
+- `@joktec/cron`: cron decorators, schedulers, job workers.
+- `@joktec/mongo`: Mongoose/Typegoose database adapter and repository.
+- `@joktec/mysql`: TypeORM relational adapter and repository.
+- `@joktec/kafka`, `@joktec/rabbit`, `@joktec/sqs`, `@joktec/redcast`: broker clients and decorators.
+- `@joktec/cacher`, `@joktec/mailer`, `@joktec/notifier`, `@joktec/storage`: external capability adapters.
+- `@joktec/elastic`, `@joktec/arango`, `@joktec/bigquery`: extended database clients.
+- `@joktec/firebase`, `@joktec/gpt`: third-party integrations.
+- `@joktec/http`, `@joktec/file`, `@joktec/alert`: reusable tools.
+
+## Dependency Direction
+
+Consumer apps depend on concrete `@joktec/*` packages. Concrete packages usually depend on `@joktec/core` and `@joktec/utils`. Keep app-specific schemas, handlers, and business semantics outside reusable packages.
+
+## Common Consumer App Pattern
+
+1. Register package modules in the app module or repository module.
+2. Keep app schemas/entities and app repositories in the consumer app.
+3. Extend the package repository base class when the package provides one.
+4. Use `BaseService`, `BaseController`, or transport helpers from `@joktec/core` when the app follows standard CRUD or message patterns.

package/dist/windsurf/.windsurf/rules/joktec-integration-skill.md

@@ -0,0 +1,35 @@
+# JokTec Integration Skill
+
+Use when wiring or using JokTec integration packages @joktec/firebase or @joktec/gpt, including validated config, SDK client lifecycle, app-neutral integration services, credentials handling, and consumer app composition.
+
+Use this skill for third-party integration packages.
+
+## Packages
+
+- `@joktec/firebase`: Firebase Admin SDK integration.
+- `@joktec/gpt`: GPT/OpenAI-style client integration.
+
+## Rules
+
+- Keep credentials config-driven and never commit real credentials.
+- Use package services instead of direct SDK initialization in app code.
+- Preserve app-neutral service behavior; consumer apps own domain workflows.
+- Verify current package README/source before relying on advanced provider features.
+
+## Reference
+
+Read `references/integrations.md` for provider-specific notes.
+
+## Bundled References
+
+### references/integrations.md
+
+# Integration Usage
+
+## Firebase
+
+Use the integration module and service to initialize Firebase Admin clients from validated config. Keep credential files local or environment-provided.
+
+## GPT
+
+Use the integration package for reusable GPT client setup. Keep prompt/business policy in the consumer app, not in the generic package.

package/dist/windsurf/.windsurf/rules/joktec-mongo-skill.md

@@ -0,0 +1,64 @@
+# JokTec Mongo Skill
+
+Use when working with @joktec/mongo in a consumer app, including MongoModule setup, Typegoose schema decorators, MongoRepo, MongoService, MongoHelper, plugins, ObjectId/query safety, soft delete, strict references, and cursor pagination.
+
+Use this skill for MongoDB-backed resources that rely on JokTec's Mongoose/Typegoose wrapper.
+
+## Rules
+
+- Register app schema classes through `MongoModule.forRoot(...)`.
+- Keep schema classes, app repositories, and app-specific queries in the consumer app.
+- Extend `MongoRepo<T, ID>` for app repositories.
+- Preserve `conId` when the app has multiple Mongo connections.
+- Use schema-first decorators when a schema class should be reused as a DTO source.
+- Treat ObjectId casting and regex behavior as safety-sensitive.
+
+## References
+
+- Read `references/repository.md` for `MongoService`, `MongoRepo`, query parsing, and cursor pagination.
+- Read `references/schema-and-plugins.md` for decorators, paranoid soft delete, strict references, transform behavior, and debug output.
+
+## Bundled References
+
+### references/repository.md
+
+# Mongo Repository Usage
+
+## Module Setup
+
+Register schemas with `MongoModule.forRoot({ conId, models: [...] })`. Use the same `conId` in app repositories when using non-default connections.
+
+## Repository Pattern
+
+Extend `MongoRepo` and pass the schema class to the base constructor. Services can then use `BaseService` from `@joktec/core`.
+
+## Query Safety
+
+- Root `id` can act as an API alias for `_id` in query conditions.
+- ObjectId casting should be schema-aware and limited to `_id`, ObjectId paths, or explicitly configured paths.
+- `$like`, `$begin`, and `$end` escape regex input by default.
+- Do not rely on broad conversion when storing raw snapshots, maps, or nested subdocuments.
+
+## Pagination
+
+`MongoRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `_id`; custom `cursorKey` appends `_id` as a tie-breaker.
+
+### references/schema-and-plugins.md
+
+# Mongo Schema And Plugins
+
+## Schema Decorators
+
+Use `@Schema` and `@Prop` wrappers from `@joktec/mongo` for Typegoose schema metadata plus validation, transform, and Swagger metadata.
+
+Avoid mutating shared option objects across multiple properties.
+
+## Plugins
+
+- Paranoid plugin handles soft delete filtering and must respect aggregate first-stage constraints such as `$geoNear`.
+- Strict reference plugin validates referenced documents and must resolve models through the active connection.
+- Transform plugin centralizes common document transformation and should not break Mongo update operators.
+
+## Debug Output
+
+Use `mongoDebug(collection, method, ...args)` when a Mongoose debug callback should be rendered as a Mongo shell-friendly command.

package/dist/windsurf/.windsurf/rules/joktec-mysql-skill.md

@@ -0,0 +1,65 @@
+# JokTec MySQL Skill
+
+Use when working with @joktec/mysql in a consumer app, including MysqlModule setup, TypeORM entities, schema-first @Column/@PrimaryColumn decorators, MysqlRepo, MysqlService, transactions, dialect support, uuidv7 ids, query safety, and cursor pagination.
+
+Use this skill for relational resources backed by JokTec's TypeORM wrapper.
+
+## Rules
+
+- Register app entities through `MysqlModule.forRoot(...)`.
+- Keep entities, app repositories, and app-specific SQL in the consumer app.
+- Extend `MysqlRepo<T, ID>` for app repositories.
+- Treat `mysql`, `mariadb`, and `postgres` as the first-class dialects.
+- Keep `sync` explicit and normally enabled only by an owner process or development bootstrap.
+- Do not add new behavior to deprecated `MysqlFinder`; use `MysqlRepo.qb()` and `MysqlHelper` paths.
+
+## References
+
+- Read `references/repository.md` for connection lifecycle, repository usage, query safety, transaction, and cursor behavior.
+- Read `references/entities.md` for `@Tables`, `@Column`, `@PrimaryColumn`, uuidv7, and dialect guidance.
+
+## Bundled References
+
+### references/entities.md
+
+# MySQL Entity Decorators
+
+## Schema-First Entity Pattern
+
+Use `@Tables`, `@Column`, and `@PrimaryColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
+
+## Primary Keys
+
+- Prefer numeric auto-increment keys for write-heavy MySQL tables.
+- Use UUIDs when the app needs globally unique or public identifiers.
+- Prefer `uuidv7` over random UUIDs when the id participates in ordered indexes or cursor-like access.
+
+## Dialects
+
+The stable dialects are MySQL, MariaDB, and Postgres. Dialect capabilities own differences such as `LIKE` vs `ILIKE`, array support, fulltext support, and generated map reliability.
+
+### references/repository.md
+
+# MySQL Repository Usage
+
+## Module Setup
+
+Register entities with `MysqlModule.forRoot({ conId, models: [...] })`. Use `conId` for multiple DataSources.
+
+## Repository Pattern
+
+Extend `MysqlRepo` and pass the entity class to the base constructor. Services can use `BaseService` when CRUD behavior follows the shared contract.
+
+## Query Safety
+
+- Validate field paths against TypeORM metadata before interpolating SQL identifiers.
+- Use parameter binding for values.
+- Keep logical operators such as `$and` and `$or` grouped through QueryBuilder behavior.
+
+## Pagination
+
+`MysqlRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `createdAt` plus primary key columns. Custom cursor keys must be mapped columns.
+
+## Transactions
+
+When using transaction-scoped operations, pass the manager or query runner through repository options so pre-read and write operations use the same context.

package/dist/windsurf/.windsurf/rules/joktec-tool-skill.md

@@ -0,0 +1,40 @@
+# JokTec Tool Skill
+
+Use when wiring or using JokTec tool packages @joktec/http, @joktec/file, or @joktec/alert, including Axios-backed HTTP clients, file classification helpers, Slack-compatible alert webhooks, config-driven lifecycle, and app-neutral utility services.
+
+Use this skill for reusable utility services.
+
+## Packages
+
+- `@joktec/http`: Axios-backed HTTP client wrapper.
+- `@joktec/file`: file classification and local file helpers.
+- `@joktec/alert`: alert delivery through Slack-compatible webhooks.
+
+## Rules
+
+- Keep tools app-neutral and reusable.
+- Use config-driven clients instead of direct ad hoc setup in app code.
+- Preserve retry, metrics, proxy, and upload behavior where the package exposes it.
+- Keep alert tokens and webhook URLs in runtime config only.
+
+## Reference
+
+Read `references/tools.md` for package-specific usage notes.
+
+## Bundled References
+
+### references/tools.md
+
+# Tool Usage
+
+## HTTP
+
+Use `@joktec/http` for Axios-backed requests, uploads, proxy agent support, retry config, and metrics where exposed.
+
+## File
+
+Use `@joktec/file` for shared file helpers and classification behavior instead of duplicating local utility code.
+
+## Alert
+
+Use `@joktec/alert` for Slack-compatible webhook alerts. Keep webhook URLs and credentials out of source control.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@joktec/skills",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Hybrid agent skill pack for using @joktec/* libraries in consumer projects.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@11.8.0",
+  "engines": {
+    "node": ">=18.18"
+  },
+  "keywords": [
+    "joktec",
+    "skills",
+    "agent",
+    "codex",
+    "claude",
+    "cursor",
+    "gemini",
+    "copilot",
+    "windsurf"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joktec/joktec-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joktec/joktec-skills/issues"
+  },
+  "homepage": "https://github.com/joktec/joktec-skills#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "skills": "./bin/joktec-skills.mjs",
+    "joktec-skills": "./bin/joktec-skills.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "LICENSE",
+    "README.md",
+    "adapters",
+    "bin",
+    "dist",
+    "scripts",
+    "skill-pack.json",
+    "skills"
+  ],
+  "scripts": {
+    "check": "node scripts/validate-skills.mjs && node scripts/sync-from-joktec-framework.mjs --check",
+    "validate": "node scripts/validate-skills.mjs",
+    "build": "node scripts/build-skill-folders.mjs && node scripts/build-cursor-rules.mjs && node scripts/build-gemini-md.mjs && node scripts/build-copilot-instructions.mjs && node scripts/build-windsurf-rules.mjs",
+    "build:skills": "node scripts/build-skill-folders.mjs",
+    "build:cursor": "node scripts/build-cursor-rules.mjs",
+    "build:gemini": "node scripts/build-gemini-md.mjs",
+    "build:copilot": "node scripts/build-copilot-instructions.mjs",
+    "build:windsurf": "node scripts/build-windsurf-rules.mjs",
+    "sync:check": "node scripts/sync-from-joktec-framework.mjs --check",
+    "prepack": "pnpm run build && pnpm run check",
+    "pack:check": "pnpm pack --dry-run",
+    "prepublish:check": "pnpm run build && pnpm run check && pnpm pack --dry-run",
+    "publish:dry-run": "pnpm run prepublish:check && pnpm publish --dry-run --no-git-checks --access public --registry https://registry.npmjs.org/",
+    "publish:registry": "pnpm run prepublish:check && pnpm publish --access public --registry https://registry.npmjs.org/",
+    "release:patch": "pnpm version patch && pnpm run publish:registry",
+    "release:minor": "pnpm version minor && pnpm run publish:registry",
+    "release:major": "pnpm version major && pnpm run publish:registry"
+  }
+}

package/scripts/build-copilot-instructions.mjs

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { DIST_DIR, ensureDir, loadSkills, outputEnabled, renderSkillWithReferences, writeFile } from './lib.mjs';
+
+const outDir = path.join(DIST_DIR, 'copilot', '.github');
+ensureDir(outDir);
+
+const { skills } = loadSkills();
+const sections = skills
+  .filter(item => outputEnabled(item, 'copilot'))
+  .map(skill => `## ${skill.meta.title}\n\n${renderSkillWithReferences(skill, { stripTitle: true })}`);
+
+writeFile(
+  path.join(outDir, 'copilot-instructions.md'),
+  `# JokTec Copilot Instructions
+
+Use these instructions when working in repositories that consume \`@joktec/*\` packages.
+
+${sections.join('\n\n---\n\n')}
+`,
+);
+
+console.log(`Generated Copilot instructions: ${path.join(outDir, 'copilot-instructions.md')}`);

package/scripts/build-cursor-rules.mjs

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { DIST_DIR, cleanDir, loadSkills, outputEnabled, renderSkillWithReferences, writeFile } from './lib.mjs';
+
+const outDir = path.join(DIST_DIR, 'cursor', '.cursor', 'rules');
+cleanDir(outDir);
+
+const { skills } = loadSkills();
+for (const skill of skills.filter(item => outputEnabled(item, 'cursor'))) {
+  const globs = skill.meta.scope?.paths?.join(',') || '**/*';
+  const content = `---
+description: ${skill.frontmatter.description}
+globs: ${globs}
+alwaysApply: false
+---
+
+# ${skill.meta.title}
+
+${renderSkillWithReferences(skill, { stripTitle: true })}
+`;
+  writeFile(path.join(outDir, `${skill.id}.mdc`), content);
+}
+
+console.log(`Generated Cursor rules: ${outDir}`);

package/scripts/build-gemini-md.mjs

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { DIST_DIR, ensureDir, loadSkills, outputEnabled, renderSkillWithReferences, writeFile } from './lib.mjs';
+
+const outDir = path.join(DIST_DIR, 'gemini');
+ensureDir(outDir);
+
+const { pack, skills } = loadSkills();
+const sections = skills
+  .filter(item => outputEnabled(item, 'gemini'))
+  .map(skill => `## ${skill.meta.title}\n\nPackages: ${skill.meta.packages.join(', ')}\n\n${renderSkillWithReferences(skill, { stripTitle: true })}`);
+
+writeFile(
+  path.join(outDir, 'GEMINI.md'),
+  `# ${pack.name}
+
+Use these instructions when working in a project that consumes JokTec packages.
+
+${sections.join('\n\n---\n\n')}
+`,
+);
+
+console.log(`Generated Gemini context: ${path.join(outDir, 'GEMINI.md')}`);

package/scripts/build-skill-folders.mjs

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIST_DIR, SKILLS_DIR, cleanDir, ensureDir } from './lib.mjs';
+
+for (const target of ['codex', 'claude']) {
+  const outDir = path.join(DIST_DIR, target, 'skills');
+  cleanDir(outDir);
+
+  for (const item of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+    if (!item.isDirectory()) continue;
+    fs.cpSync(path.join(SKILLS_DIR, item.name), path.join(outDir, item.name), { recursive: true });
+  }
+
+  ensureDir(outDir);
+  console.log(`Generated ${target} skill folders: ${outDir}`);
+}

package/scripts/build-windsurf-rules.mjs

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { DIST_DIR, cleanDir, loadSkills, outputEnabled, renderSkillWithReferences, writeFile } from './lib.mjs';
+
+const outDir = path.join(DIST_DIR, 'windsurf', '.windsurf', 'rules');
+cleanDir(outDir);
+
+const { skills } = loadSkills();
+for (const skill of skills.filter(item => outputEnabled(item, 'windsurf'))) {
+  const content = `# ${skill.meta.title}
+
+${skill.frontmatter.description}
+
+${renderSkillWithReferences(skill, { stripTitle: true })}
+`;
+  writeFile(path.join(outDir, `${skill.id}.md`), content);
+}
+
+console.log(`Generated Windsurf rules: ${outDir}`);

package/scripts/lib.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const ROOT = path.resolve(new URL('..', import.meta.url).pathname);
+export const SKILLS_DIR = path.join(ROOT, 'skills');
+export const DIST_DIR = path.join(ROOT, 'dist');
+export const PACK_PATH = path.join(ROOT, 'skill-pack.json');
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+export function listSkillDirs() {
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter(item => item.isDirectory())
+    .map(item => path.join(SKILLS_DIR, item.name))
+    .sort();
+}
+
+export function parseSkill(file) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) throw new Error(`Missing frontmatter: ${file}`);
+
+  const frontmatter = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    frontmatter[key] = value;
+  }
+
+  return {
+    file,
+    dir: path.dirname(file),
+    raw,
+    frontmatter,
+    body: match[2].trim(),
+  };
+}
+
+export function loadSkills() {
+  const pack = readJson(PACK_PATH);
+  const skillsById = new Map(listSkillDirs().map(dir => {
+    const skill = parseSkill(path.join(dir, 'SKILL.md'));
+    const id = path.basename(dir);
+    const meta = pack.skills.find(item => item.id === id);
+    if (!meta) throw new Error(`Missing skill-pack metadata for ${id}`);
+    return [id, { id, meta, ...skill }];
+  }));
+
+  const skills = pack.skills.map(meta => {
+    const skill = skillsById.get(meta.id);
+    if (!skill) throw new Error(`Missing skill directory for ${meta.id}`);
+    return skill;
+  });
+
+  return { pack, skills };
+}
+
+export function readReferences(skill) {
+  const refDir = path.join(skill.dir, 'references');
+  if (!fs.existsSync(refDir)) return [];
+
+  return fs
+    .readdirSync(refDir, { withFileTypes: true })
+    .filter(item => item.isFile() && item.name.endsWith('.md'))
+    .map(item => {
+      const file = path.join(refDir, item.name);
+      return {
+        name: item.name,
+        rel: path.relative(skill.dir, file),
+        content: fs.readFileSync(file, 'utf8').trim(),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function stripLeadingHeading(content) {
+  return content.replace(/^# .+\n+/, '').trim();
+}
+
+export function renderSkillWithReferences(skill, options = {}) {
+  const refs = readReferences(skill);
+  const body = options.stripTitle ? stripLeadingHeading(skill.body) : skill.body;
+  const refText = refs.length
+    ? `\n\n## Bundled References\n\n${refs.map(ref => `### ${ref.rel}\n\n${ref.content}`).join('\n\n')}`
+    : '';
+  return `${body}${refText}`.trim();
+}
+
+export function writeFile(file, content) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${content.replace(/\s+$/g, '')}\n`);
+}
+
+export function cleanDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+  ensureDir(dir);
+}
+
+export function outputEnabled(skill, target) {
+  return Boolean(skill.meta.outputs?.[target]);
+}

package/scripts/sync-from-joktec-framework.mjs

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DIST_DIR, ROOT, ensureDir, readJson, writeFile } from './lib.mjs';
+
+const args = new Set(process.argv.slice(2));
+const checkOnly = args.has('--check');
+const pack = readJson(path.join(ROOT, 'skill-pack.json'));
+const sourceRoot = path.resolve(ROOT, pack.sourceOfTruth);
+
+const requiredFiles = [
+  'AGENTS.md',
+  'docs/agents/ARCHITECTURE.md',
+  'docs/agents/PROJECT_CONTEXT.md',
+  'docs/agents/RUNTIME.md',
+  'docs/agents/CONTRACTS.md',
+  'packages/common/AGENTS.md',
+  'packages/common/core/AGENTS.md',
+  'packages/databases/mongo/AGENTS.md',
+  'packages/databases/mongo/README.md',
+  'packages/databases/mysql/AGENTS.md',
+  'packages/databases/mysql/README.md',
+  'packages/brokers/AGENTS.md',
+  'packages/adapters/AGENTS.md',
+  'packages/integrations/AGENTS.md',
+  'packages/tools/AGENTS.md'
+];
+
+const missing = requiredFiles.filter(file => !fs.existsSync(path.join(sourceRoot, file)));
+if (missing.length) {
+  console.error(`Missing source files from ${sourceRoot}:\n${missing.map(file => `- ${file}`).join('\n')}`);
+  process.exit(1);
+}
+
+const index = requiredFiles.map(file => {
+  const abs = path.join(sourceRoot, file);
+  const content = fs.readFileSync(abs, 'utf8');
+  return {
+    file,
+    bytes: Buffer.byteLength(content),
+    lines: content.split(/\r?\n/).length,
+    headings: content
+      .split(/\r?\n/)
+      .filter(line => /^#{1,3}\s+/.test(line))
+      .slice(0, 20),
+  };
+});
+
+if (!checkOnly) {
+  ensureDir(path.join(DIST_DIR, 'source'));
+  writeFile(path.join(DIST_DIR, 'source', 'joktec-framework-index.json'), JSON.stringify(index, null, 2));
+}
+
+console.log(`Source sync check passed for ${requiredFiles.length} files from ${sourceRoot}`);