@codepassion/skills 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
   "license": "MIT",
   "type": "module",

package/skills/c9n/SKILL.md

@@ -172,3 +172,68 @@ Alpha: tag from develop, `git tag -a vX.Y.Z -m "Release vX.Y.Z" && git push orig
 Production: confirm Go → pull release branch → create release → CI deploys → monitor.
 Reference: https://semver.org/spec/v2.0.0.html
 
+
+
+---
+
+## Deliverables
+
+Repeatable customer project delivery for the Code Passion team. Turns a codebase into a
+clean, customer-ready documentation package. Fully generic — adapt to whatever stack the
+project uses. Bundled `scripts/` are proven references; read and adapt them per project.
+
+## Four mandatory gates
+
+These ALWAYS run, in order — never skip them:
+
+1. **Clarify-first** — interview before generating anything (see Workflow step 1).
+2. **Security/sanitize** — never ship secrets. Before packaging: scan for and exclude
+   `.env`, credentials, service-account JSON, `*.pem`/`*.key`; sanitize real env files to
+   `.env.example` (names + descriptions, no values); strip `.DS_Store`. If you copied any
+   credential into a build dir to make tooling work, delete it before finishing.
+3. **Verify rendered output** — after creating PDFs, screenshot each (headless browser
+   `--screenshot`) and visually confirm. Catches illegible/empty diagrams and truncation.
+   Do not trust `file`'s page count — use `mdls -name kMDItemNumberOfPages` on macOS.
+4. **Delivery email** — always draft one. Thai for Thai customer teams, Code Passion
+   framing (from Code Passion → client). Leave recipient/contact as fill-in blanks.
+
+## Workflow
+
+1. **Clarify** (ask, don't assume): audience (customer vs internal); which documents are
+   wanted; document language (default: English docs + Thai email); output format (PDF?);
+   package structure — **plain docs package (default)** or **ISO/IEC 29110 work-product
+   layout** (offer it, see [REFERENCE.md](../c9n-deliverables/REFERENCE.md)); any contractual scope.
+2. **Inventory** the codebase — detect stack, framework, DB, API doc tooling; decide which
+   generators apply. Skip what doesn't fit the stack.
+3. **Generate** the doc set (only what was requested). Common artifacts and recipes are in
+   [REFERENCE.md](../c9n-deliverables/REFERENCE.md): system/architecture overview (+ Mermaid diagrams),
+   database design (ER diagram + data dictionary), API reference (export spec → PDF),
+   deployment runbook, configuration reference, source snapshot.
+4. **Render PDFs** with `scripts/md-to-pdf.mjs` (Markdown+Mermaid) and
+   `scripts/openapi-to-pdf.mjs` (OpenAPI). Then run gate 3 (verify).
+5. **Organize** per the chosen structure. Master `README.md` index; for 29110 include a
+   supporting-artifact → work-product traceability map.
+6. **Security gate** (gate 2), then **package**: zip the organized folder directly (or, if a
+   dedicated packaging skill such as `deliverables-packager` is installed, hand off to it for
+   final folder polish + zip).
+7. **Delivery email** (gate 4).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/md-to-pdf.mjs <in.md> <out.pdf>` | Markdown → PDF, renders Mermaid. Needs a Chromium-family browser. |
+| `scripts/openapi-to-pdf.mjs <spec.json> <out.pdf> [guide.md]` | OpenAPI → print-friendly PDF (no lazy-load truncation). |
+| `scripts/export-openapi.cjs <out.json>` | TEMPLATE: boot a NestJS app, dump Swagger spec. Adapt to project. |
+| `scripts/data-dictionary.cjs <out.md>` | Data dictionary from live MySQL `INFORMATION_SCHEMA`. |
+| `scripts/snapshot-source.sh <repo> <out.zip>` | Clean `git archive` source snapshot. |
+
+## Gotchas
+
+- **Wide Mermaid diagrams** render as an illegible strip at page width. Use `flowchart TB`
+  and split large ER diagrams into per-domain groups (portrait aspect ratio).
+- **OpenAPI export**: build first (`nest build`); ts-node mis-emits decorator metadata.
+  Booting connects to the DB — use a dev DB, never production.
+- **Redoc/Swagger UI → PDF**: they lazy-render; printing truncates. Use `openapi-to-pdf.mjs`.
+- See [REFERENCE.md](../c9n-deliverables/REFERENCE.md) for the ISO/IEC 29110 layout and per-artifact recipes.
+

package/skills/c9n-deliverables/REFERENCE.md

@@ -0,0 +1,97 @@
+# C9N Deliverables — Reference
+
+## Document set (artifacts & recipes)
+
+Generate only what the clarify step asked for. Each is a Markdown source rendered to PDF.
+
+### System / Architecture Overview
+- Content: tech stack table, module map, auth model, API versioning, **architecture
+  diagrams** (Mermaid `flowchart`): System Context, Layered Request Flow, Deployment.
+- Source from README + code structure. Render with `md-to-pdf.mjs`.
+- Keep flow diagrams `flowchart TB` so they stay legible at page width.
+
+### Database Design
+- ER diagram(s) as Mermaid `erDiagram`. **Split into per-domain groups** — one giant ER is
+  unreadable. Plus a domain-grouped entity catalog.
+- **Data dictionary**: every table & column. Generate from the live DB with
+  `data-dictionary.cjs` (most accurate) — adjust the env var names to the project.
+
+### API Reference
+- Export the spec from the running/built app (`export-openapi.cjs` for NestJS/Swagger, or
+  `curl <host>/api-json`). Render with `openapi-to-pdf.mjs` (optionally pass a guide.md
+  intro covering auth, versioning, how to import the spec).
+- Also ship `openapi.json` (Postman/codegen) and optionally a Redoc HTML for browsing.
+
+### Deployment Runbook
+- Prerequisites, env vars (point to `.env.example`), local dev, build, Docker, CI/CD
+  (e.g. Cloud Build → Cloud Run), production checklist, troubleshooting.
+
+### Configuration Reference
+- Sanitized `.env.example` — variable names + descriptions, **no values**. Plus notes on
+  Docker/compose/CI config files.
+
+### Source Code Snapshot
+- `snapshot-source.sh <repo> <out.zip>`. Run at final delivery so it isn't stale.
+
+## Plain docs package layout (default)
+
+```
+deliverables/
+├── README.md                  # index
+├── 01-documentation/
+│   ├── markdown/              # editable sources
+│   └── pdf/                   # rendered PDFs
+├── 02-database/              # data dictionary, ER
+├── 03-configuration/        # .env.example, notes
+├── 04-utilities/            # helper scripts
+└── 05-source-code/          # snapshot (or placeholder)
+```
+
+## ISO/IEC 29110 layout (Basic Profile, offer when engagement needs it)
+
+Two process groups. Formal work products at their slots; supporting engineering artifacts
+filed under the SI work product they evidence, with a traceability map in the README.
+
+```
+deliverables/
+├── README.md                         # master index + traceability
+├── 00-project-management/            # PM work products
+│   ├── PM-01_Statement-of-Work.pdf
+│   ├── PM-02_Project-Plan.pdf
+│   ├── PM-03_Progress-Status-Record.pdf
+│   ├── PM-04_Change-Request.pdf
+│   ├── PM-05_Acceptance-Record.pdf
+│   └── PM-06_Verification-Validation-Record.pdf
+└── 01-software-implementation/       # SI work products
+    ├── SI-01_Requirements-Specification.pdf
+    ├── SI-02_Software-Design.pdf
+    ├── SI-03_Traceability-Record.pdf
+    ├── SI-04_Test-Cases-and-Procedures.pdf
+    ├── SI-05_Test-Report.pdf
+    ├── SI-06_Product-Operation-Guide.pdf
+    ├── SI-07_Maintenance-Documentation.pdf
+    └── supporting/
+        ├── architecture/   → SI.2
+        ├── database/       → SI.2
+        ├── api/            → SI.2 (interfaces)
+        ├── operations/     → SI.6 / SI.7
+        └── source-code/    → SI Software Components
+```
+
+Traceability: architecture/database/api → **SI.2 Software Design**; operations →
+**SI.6 Product Operation Guide** + **SI.7 Maintenance**; source-code → **SI Software
+Components**. PM acceptance/sign-off rows stay open for the customer.
+
+## Delivery email shape (Thai default)
+
+- Subject: `ส่งมอบชุด Deliverables โครงการ [PROJECT]`
+- From Code Passion → customer team. One paragraph: package attached. One: contents
+  overview. One: PDFs for reading + Markdown sources retained. Note where the source
+  snapshot lives. Close with support availability. Leave `[ชื่อผู้รับ]` / `[ช่องทางติดต่อ]` blanks.
+
+## Dependency notes
+
+- PDF rendering needs a Chromium-family browser (Brave/Chrome/Edge/Chromium). Never auto-
+  install heavy deps (puppeteer, pandoc, LaTeX) without asking the user first.
+- `data-dictionary.cjs` needs `mysql2` resolvable from a project that has it.
+- Mermaid + marked load from CDN → diagram rendering needs internet.

package/skills/c9n-deliverables/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: c9n-deliverables
+description: Generate a customer-facing delivery/handover package FROM a codebase — architecture docs, ER/data-dictionary, API reference, all rendered to PDF, organized, security-scanned, zipped, with a delivery email. Use when handing a project off to a customer or another team, preparing deliverables, "delivery package", "handover", "ส่งมอบงาน", or when asked to document a codebase for an external recipient. Complements deliverables-packager (this generates docs from code + organizes; that packages existing docs).
+---
+
+Repeatable customer project delivery for the Code Passion team. Turns a codebase into a
+clean, customer-ready documentation package. Fully generic — adapt to whatever stack the
+project uses. Bundled `scripts/` are proven references; read and adapt them per project.
+
+## Four mandatory gates
+
+These ALWAYS run, in order — never skip them:
+
+1. **Clarify-first** — interview before generating anything (see Workflow step 1).
+2. **Security/sanitize** — never ship secrets. Before packaging: scan for and exclude
+   `.env`, credentials, service-account JSON, `*.pem`/`*.key`; sanitize real env files to
+   `.env.example` (names + descriptions, no values); strip `.DS_Store`. If you copied any
+   credential into a build dir to make tooling work, delete it before finishing.
+3. **Verify rendered output** — after creating PDFs, screenshot each (headless browser
+   `--screenshot`) and visually confirm. Catches illegible/empty diagrams and truncation.
+   Do not trust `file`'s page count — use `mdls -name kMDItemNumberOfPages` on macOS.
+4. **Delivery email** — always draft one. Thai for Thai customer teams, Code Passion
+   framing (from Code Passion → client). Leave recipient/contact as fill-in blanks.
+
+## Workflow
+
+1. **Clarify** (ask, don't assume): audience (customer vs internal); which documents are
+   wanted; document language (default: English docs + Thai email); output format (PDF?);
+   package structure — **plain docs package (default)** or **ISO/IEC 29110 work-product
+   layout** (offer it, see [REFERENCE.md](../c9n-deliverables/REFERENCE.md)); any contractual scope.
+2. **Inventory** the codebase — detect stack, framework, DB, API doc tooling; decide which
+   generators apply. Skip what doesn't fit the stack.
+3. **Generate** the doc set (only what was requested). Common artifacts and recipes are in
+   [REFERENCE.md](../c9n-deliverables/REFERENCE.md): system/architecture overview (+ Mermaid diagrams),
+   database design (ER diagram + data dictionary), API reference (export spec → PDF),
+   deployment runbook, configuration reference, source snapshot.
+4. **Render PDFs** with `scripts/md-to-pdf.mjs` (Markdown+Mermaid) and
+   `scripts/openapi-to-pdf.mjs` (OpenAPI). Then run gate 3 (verify).
+5. **Organize** per the chosen structure. Master `README.md` index; for 29110 include a
+   supporting-artifact → work-product traceability map.
+6. **Security gate** (gate 2), then **package**: zip the organized folder directly (or, if a
+   dedicated packaging skill such as `deliverables-packager` is installed, hand off to it for
+   final folder polish + zip).
+7. **Delivery email** (gate 4).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/md-to-pdf.mjs <in.md> <out.pdf>` | Markdown → PDF, renders Mermaid. Needs a Chromium-family browser. |
+| `scripts/openapi-to-pdf.mjs <spec.json> <out.pdf> [guide.md]` | OpenAPI → print-friendly PDF (no lazy-load truncation). |
+| `scripts/export-openapi.cjs <out.json>` | TEMPLATE: boot a NestJS app, dump Swagger spec. Adapt to project. |
+| `scripts/data-dictionary.cjs <out.md>` | Data dictionary from live MySQL `INFORMATION_SCHEMA`. |
+| `scripts/snapshot-source.sh <repo> <out.zip>` | Clean `git archive` source snapshot. |
+
+## Gotchas
+
+- **Wide Mermaid diagrams** render as an illegible strip at page width. Use `flowchart TB`
+  and split large ER diagrams into per-domain groups (portrait aspect ratio).
+- **OpenAPI export**: build first (`nest build`); ts-node mis-emits decorator metadata.
+  Booting connects to the DB — use a dev DB, never production.
+- **Redoc/Swagger UI → PDF**: they lazy-render; printing truncates. Use `openapi-to-pdf.mjs`.
+- See [REFERENCE.md](../c9n-deliverables/REFERENCE.md) for the ISO/IEC 29110 layout and per-artifact recipes.

package/skills/c9n-deliverables/scripts/data-dictionary.cjs

@@ -0,0 +1,49 @@
+// Generate a data dictionary (Markdown) from a live MySQL/MariaDB INFORMATION_SCHEMA.
+// Schema only — no row data. Requires `mysql2` resolvable (run from a project that has it).
+//
+// Usage:  node data-dictionary.cjs <output.md>
+// Env (or a .env loaded via dotenv): SQL_HOST SQL_PORT SQL_USERNAME SQL_PASSWORD SQL_DATABASE_1
+//   Adjust the env var names below to match the target project's config.
+const mysql = require('mysql2/promise')
+const fs = require('fs')
+
+const OUT = process.argv[2]
+if (!OUT) { console.error('usage: node data-dictionary.cjs <output.md>'); process.exit(2) }
+try { require('dotenv').config({ path: process.env.ENV_FILE || '.env' }) } catch {}
+
+const cfg = {
+  host: process.env.SQL_HOST || process.env.DB_HOST,
+  port: +(process.env.SQL_PORT || process.env.DB_PORT || 3306),
+  user: process.env.SQL_USERNAME || process.env.DB_USER,
+  password: process.env.SQL_PASSWORD || process.env.DB_PASSWORD,
+  database: process.env.SQL_DATABASE_1 || process.env.DB_NAME,
+}
+const esc = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+
+;(async () => {
+  const c = await mysql.createConnection({ ...cfg, connectTimeout: 10000 })
+  const [tables] = await c.query(
+    `SELECT TABLE_NAME, TABLE_COMMENT,
+            (SELECT COUNT(*) FROM information_schema.columns col WHERE col.table_schema=t.table_schema AND col.table_name=t.table_name) COLS
+     FROM information_schema.tables t WHERE t.table_schema=? AND t.table_type='BASE TABLE' ORDER BY t.table_name`, [cfg.database])
+  const [cols] = await c.query(
+    `SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, EXTRA, COLUMN_COMMENT
+     FROM information_schema.columns WHERE table_schema=? ORDER BY TABLE_NAME, ORDINAL_POSITION`, [cfg.database])
+  const byTable = {}
+  for (const col of cols) (byTable[col.TABLE_NAME] ||= []).push(col)
+
+  let md = `# Data Dictionary\n\nGenerated from the live database schema (\`INFORMATION_SCHEMA\`). **${tables.length} tables.**\n\n## Tables\n\n`
+  for (const t of tables) md += `- [${t.TABLE_NAME}](#${t.TABLE_NAME.toLowerCase()}) (${t.COLS} columns)\n`
+  md += `\n---\n\n`
+  for (const t of tables) {
+    md += `### ${t.TABLE_NAME}\n\n`
+    if (t.TABLE_COMMENT) md += `${esc(t.TABLE_COMMENT)}\n\n`
+    md += `| Column | Type | Null | Key | Default | Extra | Comment |\n|--------|------|------|-----|---------|-------|--------|\n`
+    for (const col of byTable[t.TABLE_NAME] || [])
+      md += `| ${esc(col.COLUMN_NAME)} | \`${esc(col.COLUMN_TYPE)}\` | ${col.IS_NULLABLE} | ${esc(col.COLUMN_KEY)} | ${col.COLUMN_DEFAULT === null ? '' : esc(col.COLUMN_DEFAULT)} | ${esc(col.EXTRA)} | ${esc(col.COLUMN_COMMENT)} |\n`
+    md += `\n`
+  }
+  fs.writeFileSync(OUT, md)
+  console.log(`wrote ${OUT} — ${tables.length} tables, ${cols.length} columns`)
+  await c.end()
+})().catch((e) => { console.error('FAILED:', e.code || e.message); process.exit(1) })

package/skills/c9n-deliverables/scripts/export-openapi.cjs

@@ -0,0 +1,35 @@
+// Export the OpenAPI/Swagger spec from a NestJS app WITHOUT starting the HTTP server.
+// This is a TEMPLATE — adapt the DocumentBuilder block to match the project's main.ts.
+//
+// Usage:  node export-openapi.cjs <output.json>
+//
+// IMPORTANT notes learned the hard way:
+//  - Run against the COMPILED build (`nest build` -> dist), not ts-node. ts-node
+//    transpile-only mis-emits decorator metadata and TypeORM entity validation fails.
+//  - App bootstrap may require real resources (DB reachable, credential files present).
+//    Booting connects to the DB; use a dev DB, never production.
+//  - Match enableVersioning() and the DocumentBuilder config to the project's main.ts.
+const { NestFactory } = require('@nestjs/core')
+const { SwaggerModule, DocumentBuilder } = require('@nestjs/swagger')
+const { VersioningType } = require('@nestjs/common')
+const fs = require('fs')
+const path = require('path')
+require('reflect-metadata')
+try { require('dotenv').config({ path: process.env.ENV_FILE || '.env' }) } catch {}
+
+const OUT = process.argv[2] || 'openapi.json'
+// ADAPT: path to the compiled AppModule
+const { AppModule } = require(path.resolve(process.cwd(), 'dist/src/app.module'))
+
+;(async () => {
+  const app = await NestFactory.create(AppModule, { logger: ['error', 'warn'] })
+  // ADAPT: copy enableVersioning() from the project's main.ts if it uses versioning
+  app.enableVersioning({ type: VersioningType.URI, defaultVersion: '1', prefix: 'api/v' })
+  // ADAPT: mirror the project's DocumentBuilder (title, version, auth schemes)
+  const config = new DocumentBuilder().setTitle('API').setVersion('1.0').build()
+  const document = SwaggerModule.createDocument(app, config)
+  fs.writeFileSync(path.resolve(process.cwd(), OUT), JSON.stringify(document, null, 2))
+  console.log(`wrote ${OUT} — ${Object.keys(document.paths || {}).length} paths`)
+  await app.close()
+  process.exit(0)
+})().catch((e) => { console.error('FAILED:', e?.message || e); process.exit(1) })

package/skills/c9n-deliverables/scripts/md-to-pdf.mjs

@@ -0,0 +1,73 @@
+// Render a Markdown file to PDF via a headless Chromium browser.
+// Handles Mermaid code fences (```mermaid) by rendering them to SVG client-side.
+//
+// Usage:  node md-to-pdf.mjs <input.md> <output.pdf>
+//
+// No install required if a Chromium-family browser is present (Brave/Chrome/Edge/Chromium).
+// Mermaid + marked load from CDN, so the machine needs internet for diagram rendering.
+//
+// SECURITY: input is expected to be FIRST-PARTY documentation you generated for the
+// delivery (the project's own docs), not untrusted third-party Markdown. Mermaid runs with
+// securityLevel:'strict' (no click handlers / inline HTML in diagrams). Markdown is still
+// rendered with raw HTML allowed — do not feed this untrusted Markdown.
+//
+// NOTE: For very WIDE diagrams (many nodes in one row), prefer `flowchart TB` / vertical
+// ER layouts in the source — wide diagrams scale down to an illegible strip at page width.
+import { readFileSync, writeFileSync, mkdtempSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, basename } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const [src, out] = process.argv.slice(2)
+if (!src || !out) { console.error('usage: node md-to-pdf.mjs <input.md> <output.pdf>'); process.exit(2) }
+
+const BROWSERS = [
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+]
+const browser = BROWSERS.find(existsSync)
+if (!browser) { console.error('No Chromium-family browser found. Install Chrome/Brave/Chromium.'); process.exit(1) }
+
+const md = readFileSync(src, 'utf8')
+const html = `<!doctype html><html><head><meta charset="utf-8">
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+<style>
+  @page { margin: 18mm 16mm; }
+  body { font: 14px/1.6 -apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif; color:#1a1a1a; max-width:820px; margin:0 auto; }
+  h1 { font-size:26px; border-bottom:2px solid #222; padding-bottom:6px; }
+  h2 { font-size:20px; margin-top:28px; border-bottom:1px solid #ddd; padding-bottom:4px; }
+  h3 { font-size:16px; margin-top:20px; }
+  table { border-collapse:collapse; width:100%; margin:12px 0; font-size:13px; }
+  th,td { border:1px solid #ccc; padding:6px 10px; text-align:left; vertical-align:top; }
+  th { background:#f4f4f4; }
+  code { background:#f0f0f0; padding:1px 5px; border-radius:3px; font-size:12px; }
+  pre { background:#f6f8fa; padding:12px; border-radius:6px; overflow:auto; }
+  pre code { background:none; padding:0; }
+  .mermaid { text-align:center; margin:16px 0; }
+  blockquote { border-left:4px solid #ccc; margin:12px 0; padding:4px 14px; color:#555; }
+</style></head><body>
+<div id="out"></div>
+<script type="text/markdown" id="src">${md.replace(/<\/script>/g, '<\\/script>')}</script>
+<script>
+  document.getElementById('out').innerHTML = marked.parse(document.getElementById('src').textContent);
+  document.querySelectorAll('code.language-mermaid').forEach(c => {
+    const d = document.createElement('div'); d.className='mermaid'; d.textContent=c.textContent;
+    c.closest('pre').replaceWith(d);
+  });
+  mermaid.initialize({ startOnLoad:false, securityLevel:'strict' });
+  mermaid.run();
+</script></body></html>`
+
+const tmp = mkdtempSync(join(tmpdir(), 'md2pdf-'))
+const htmlPath = join(tmp, basename(src) + '.html')
+writeFileSync(htmlPath, html)
+execFileSync(browser, [
+  '--headless', '--disable-gpu', '--no-pdf-header-footer',
+  '--run-all-compositor-stages-before-draw', '--virtual-time-budget=20000',
+  `--print-to-pdf=${out}`, `file://${htmlPath}`,
+], { stdio: 'inherit' })
+console.log('wrote', out)

package/skills/c9n-deliverables/scripts/openapi-to-pdf.mjs

@@ -0,0 +1,78 @@
+// Render an OpenAPI 3 spec to a print-friendly PDF (no lazy loading — full content,
+// unlike Redoc/Swagger UI which lazy-render and truncate when printed).
+//
+// Usage:  node openapi-to-pdf.mjs <openapi.json> <output.pdf> [guide.md]
+//   guide.md (optional) is prepended as an intro section before the endpoint reference.
+//
+// SECURITY: the spec and guide.md are expected to be FIRST-PARTY artifacts you generated
+// for the delivery, not untrusted input. The guide Markdown is rendered with raw HTML
+// allowed — do not pass an untrusted guide file.
+import { readFileSync, writeFileSync, mkdtempSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+const [specPath, out, guidePath] = process.argv.slice(2)
+if (!specPath || !out) { console.error('usage: node openapi-to-pdf.mjs <openapi.json> <output.pdf> [guide.md]'); process.exit(2) }
+
+const BROWSERS = [
+  '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+]
+const browser = BROWSERS.find(existsSync)
+if (!browser) { console.error('No Chromium-family browser found.'); process.exit(1) }
+
+const spec = JSON.parse(readFileSync(specPath, 'utf8'))
+const guideMd = guidePath && existsSync(guidePath) ? readFileSync(guidePath, 'utf8').replace(/^# .*\r?\n/, '') : ''
+const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]))
+const refName = (r) => (r?.$ref ? r.$ref.split('/').pop() : null)
+const schemaType = (s) => !s ? '' : s.$ref ? refName(s) : s.type === 'array' ? `${schemaType(s.items)}[]` : s.enum ? `enum(${s.enum.map(esc).join(', ')})` : s.format ? `${s.type}<${s.format}>` : (s.type || 'object')
+
+const methods = ['get', 'post', 'put', 'patch', 'delete']
+const groups = {}
+for (const [p, item] of Object.entries(spec.paths || {}))
+  for (const m of methods) { const op = item[m]; if (!op) continue; const tag = (op.tags && op.tags[0]) || 'default'; (groups[tag] ||= []).push({ m, p, op }) }
+
+const pTable = (ps = []) => !ps.length ? '' : `<table class="p"><thead><tr><th>Name</th><th>In</th><th>Req</th><th>Type</th></tr></thead><tbody>${ps.map((pa) => `<tr><td><code>${esc(pa.name)}</code></td><td>${esc(pa.in)}</td><td>${pa.required ? 'yes' : 'no'}</td><td>${esc(schemaType(pa.schema))}</td></tr>`).join('')}</tbody></table>`
+const bBlock = (rb) => { if (!rb) return ''; const j = rb.content && (rb.content['application/json'] || Object.values(rb.content)[0]); return `<div class="body"><span class="lbl">Request body${rb.required ? ' (required)' : ''}:</span> <code>${esc(j ? schemaType(j.schema) : 'object')}</code></div>` }
+const rBlock = (r = {}) => { const rows = Object.entries(r).map(([c, v]) => `<tr><td><code>${esc(c)}</code></td><td>${esc(v.description || '')}</td></tr>`).join(''); return rows ? `<table class="p"><thead><tr><th>Status</th><th>Description</th></tr></thead><tbody>${rows}</tbody></table>` : '' }
+
+let body = ''
+for (const tag of Object.keys(groups).sort()) {
+  body += `<h2>${esc(tag)}</h2>`
+  for (const { m, p, op } of groups[tag])
+    body += `<div class="op"><div class="line"><span class="m ${m}">${m.toUpperCase()}</span><code class="path">${esc(p)}</code></div>${op.summary ? `<div class="sum">${esc(op.summary)}</div>` : ''}${op.description ? `<div class="desc">${esc(op.description)}</div>` : ''}${pTable(op.parameters)}${bBlock(op.requestBody)}${rBlock(op.responses)}</div>`
+}
+const opCount = Object.values(spec.paths || {}).reduce((n, it) => n + methods.filter((m) => it[m]).length, 0)
+
+const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+@page { margin: 16mm 14mm; }
+body { font: 12px/1.5 -apple-system,Segoe UI,Roboto,Arial,sans-serif; color:#1a1a1a; max-width:860px; margin:0 auto; }
+h1 { font-size:24px; border-bottom:2px solid #222; padding-bottom:6px; }
+h2 { font-size:18px; margin:26px 0 10px; border-bottom:1px solid #ddd; padding-bottom:4px; break-after:avoid; }
+.op { border:1px solid #e3e3e3; border-radius:6px; padding:10px 12px; margin:10px 0; break-inside:avoid; }
+.line { display:flex; align-items:center; gap:8px; }
+.m { color:#fff; font-weight:700; font-size:11px; padding:2px 8px; border-radius:4px; }
+.m.get{background:#2e8b57}.m.post{background:#1f6feb}.m.put{background:#b8860b}.m.patch{background:#8250df}.m.delete{background:#cf222e}
+.sum { font-weight:600; margin:6px 0 2px; } .desc { color:#555; margin:2px 0; }
+table.p { border-collapse:collapse; width:100%; margin:8px 0; font-size:11px; }
+table.p th, table.p td { border:1px solid #ddd; padding:4px 8px; text-align:left; } table.p th { background:#f5f5f5; }
+.body { margin:6px 0; } .lbl { color:#555; } code { background:#f0f0f0; padding:1px 4px; border-radius:3px; }
+.meta { color:#555; margin-bottom:18px; } .section-break { break-before:page; }
+.guide table { border-collapse:collapse; width:100%; margin:8px 0; font-size:12px; }
+.guide th, .guide td { border:1px solid #ccc; padding:5px 9px; text-align:left; } .guide th { background:#f4f4f4; }
+.guide blockquote { border-left:4px solid #ccc; margin:10px 0; padding:4px 14px; color:#555; }
+</style>${guideMd ? '<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>' : ''}</head><body>
+<h1>${esc(spec.info?.title || 'API')} — API Documentation</h1>
+<div class="meta">Version ${esc(spec.info?.version || '')} · OpenAPI ${esc(spec.openapi || '')} · ${Object.keys(spec.paths || {}).length} paths · ${opCount} operations</div>
+${guideMd ? `<div class="guide" id="guide"></div><script type="text/markdown" id="g">${guideMd.replace(/<\/script>/g, '<\\/script>')}</script><script>document.getElementById('guide').innerHTML=marked.parse(document.getElementById('g').textContent)</script><h1 class="section-break">Endpoint Reference</h1>` : ''}
+${body}
+</body></html>`
+
+const tmp = mkdtempSync(join(tmpdir(), 'oa2pdf-'))
+const htmlPath = join(tmp, 'api.html')
+writeFileSync(htmlPath, html)
+execFileSync(browser, ['--headless', '--disable-gpu', '--no-pdf-header-footer', '--run-all-compositor-stages-before-draw', '--virtual-time-budget=15000', `--print-to-pdf=${out}`, `file://${htmlPath}`], { stdio: 'inherit' })
+console.log('wrote', out)

package/skills/c9n-deliverables/scripts/snapshot-source.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Produce a clean source-code snapshot using git archive.
+# git archive only includes tracked files — node_modules, .env, dist, secrets are
+# excluded automatically (assuming they are gitignored / untracked).
+#
+# Usage:  snapshot-source.sh <repo-root> <output.zip>
+set -euo pipefail
+
+REPO_ROOT="${1:-$PWD}"
+OUT="${2:?usage: snapshot-source.sh <repo-root> <output.zip>}"
+
+# Resolve a relative <output.zip> against the caller's cwd, then use `git -C` so we
+# never change the caller's working directory. (A bare relative --output under
+# `git -C`/`cd` would surprisingly land inside the repo root.)
+case "$OUT" in /*) ;; *) OUT="$PWD/$OUT" ;; esac
+
+if [ ! -d "$REPO_ROOT/.git" ]; then
+  echo "Error: $REPO_ROOT is not a git repository." >&2
+  exit 1
+fi
+
+git -C "$REPO_ROOT" archive --format=zip --output "$OUT" HEAD
+echo "Source snapshot written to: $OUT"