@diottodev/runic 1.0.0 → 1.1.0

package/compliance/soc2-compliance/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: "soc2-compliance"
+description: "Use when the user asks to prepare for SOC 2 audits, map Trust Service Criteria, build control matrices, collect audit evidence, perform gap analysis, or assess SOC 2 Type I vs Type II readiness."
+---
+
+# SOC 2 Compliance
+
+SOC 2 Type I and Type II compliance preparation for SaaS companies. Covers Trust Service Criteria mapping, control matrix generation, evidence collection, gap analysis, and audit readiness assessment.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Trust Service Criteria](#trust-service-criteria)
+- [Control Matrix Generation](#control-matrix-generation)
+- [Gap Analysis Workflow](#gap-analysis-workflow)
+- [Evidence Collection](#evidence-collection)
+- [Audit Readiness Checklist](#audit-readiness-checklist)
+- [Vendor Management](#vendor-management)
+- [Continuous Compliance](#continuous-compliance)
+- [Anti-Patterns](#anti-patterns)
+- [Tools](#tools)
+- [References](#references)
+- [Cross-References](#cross-references)
+
+---
+
+## Overview
+
+### What Is SOC 2?
+
+SOC 2 (System and Organization Controls 2) is an auditing framework developed by the AICPA that evaluates how a service organization manages customer data. It applies to any technology company that stores, processes, or transmits customer information — primarily SaaS, cloud infrastructure, and managed service providers.
+
+### Type I vs Type II
+
+| Aspect | Type I | Type II |
+|--------|--------|---------|
+| **Scope** | Design of controls at a point in time | Design AND operating effectiveness over a period |
+| **Duration** | Snapshot (single date) | Observation window (3-12 months, typically 6) |
+| **Evidence** | Control descriptions, policies | Control descriptions + operating evidence (logs, tickets, screenshots) |
+| **Cost** | $20K-$50K (audit fees) | $30K-$100K+ (audit fees) |
+| **Timeline** | 1-2 months (audit phase) | 6-12 months (observation + audit) |
+| **Best For** | First-time compliance, rapid market need | Mature organizations, enterprise customers |
+
+### Who Needs SOC 2?
+
+- **SaaS companies** selling to enterprise customers
+- **Cloud infrastructure providers** handling customer workloads
+- **Data processors** managing PII, PHI, or financial data
+- **Managed service providers** with access to client systems
+- **Any vendor** whose customers require third-party assurance
+
+### Typical Journey
+
+```
+Gap Assessment → Remediation → Type I Audit → Observation Period → Type II Audit → Annual Renewal
+    (4-8 wk)      (8-16 wk)     (4-6 wk)       (6-12 mo)          (4-6 wk)       (ongoing)
+```
+
+---
+
+## Trust Service Criteria
+
+SOC 2 is organized around five Trust Service Criteria (TSC) categories. **Security** is required for every SOC 2 report; the remaining four are optional and selected based on business need.
+
+### Security (Common Criteria CC1-CC9) — Required
+
+The foundation of every SOC 2 report. Maps to COSO 2013 principles.
+
+| Criteria | Domain | Key Controls |
+|----------|--------|-------------|
+| **CC1** | Control Environment | Integrity/ethics, board oversight, org structure, competence, accountability |
+| **CC2** | Communication & Information | Internal/external communication, information quality |
+| **CC3** | Risk Assessment | Risk identification, fraud risk, change impact analysis |
+| **CC4** | Monitoring Activities | Ongoing monitoring, deficiency evaluation, corrective actions |
+| **CC5** | Control Activities | Policies/procedures, technology controls, deployment through policies |
+| **CC6** | Logical & Physical Access | Access provisioning, authentication, encryption, physical restrictions |
+| **CC7** | System Operations | Vulnerability management, anomaly detection, incident response |
+| **CC8** | Change Management | Change authorization, testing, approval, emergency changes |
+| **CC9** | Risk Mitigation | Vendor/business partner risk management |
+
+### Availability (A1) — Optional
+
+| Criteria | Focus | Key Controls |
+|----------|-------|-------------|
+| **A1.1** | Capacity management | Infrastructure scaling, resource monitoring, capacity planning |
+| **A1.2** | Recovery operations | Backup procedures, disaster recovery, BCP testing |
+| **A1.3** | Recovery testing | DR drills, failover testing, RTO/RPO validation |
+
+**Select when:** Customers depend on your uptime; you have SLAs; downtime causes direct business impact.
+
+### Confidentiality (C1) — Optional
+
+| Criteria | Focus | Key Controls |
+|----------|-------|-------------|
+| **C1.1** | Identification | Data classification policy, confidential data inventory |
+| **C1.2** | Protection | Encryption at rest and in transit, DLP, access restrictions |
+| **C1.3** | Disposal | Secure deletion procedures, media sanitization, retention enforcement |
+
+**Select when:** You handle trade secrets, proprietary data, or contractually confidential information.
+
+### Processing Integrity (PI1) — Optional
+
+| Criteria | Focus | Key Controls |
+|----------|-------|-------------|
+| **PI1.1** | Accuracy | Input validation, processing checks, output verification |
+| **PI1.2** | Completeness | Transaction monitoring, reconciliation, error handling |
+| **PI1.3** | Timeliness | SLA monitoring, processing delay alerts, batch job monitoring |
+| **PI1.4** | Authorization | Processing authorization controls, segregation of duties |
+
+**Select when:** Data accuracy is critical (financial processing, healthcare records, analytics platforms).
+
+### Privacy (P1-P8) — Optional
+
+| Criteria | Focus | Key Controls |
+|----------|-------|-------------|
+| **P1** | Notice | Privacy policy, data collection notice, purpose limitation |
+| **P2** | Choice & Consent | Opt-in/opt-out, consent management, preference tracking |
+| **P3** | Collection | Minimal collection, lawful basis, purpose specification |
+| **P4** | Use, Retention, Disposal | Purpose limitation, retention schedules, secure disposal |
+| **P5** | Access | Data subject access requests, correction rights |
+| **P6** | Disclosure & Notification | Third-party sharing, breach notification |
+| **P7** | Quality | Data accuracy verification, correction mechanisms |
+| **P8** | Monitoring & Enforcement | Privacy program monitoring, complaint handling |
+
+**Select when:** You process PII and customers expect privacy assurance (complements GDPR compliance).
+
+---
+
+## Control Matrix Generation
+
+A control matrix maps each TSC criterion to specific controls, owners, evidence, and testing procedures.
+
+### Matrix Structure
+
+| Field | Description |
+|-------|-------------|
+| **Control ID** | Unique identifier (e.g., SEC-001, AVL-003) |
+| **TSC Mapping** | Which criteria the control addresses (e.g., CC6.1, A1.2) |
+| **Control Description** | What the control does |
+| **Control Type** | Preventive, Detective, or Corrective |
+| **Owner** | Responsible person/team |
+| **Frequency** | Continuous, Daily, Weekly, Monthly, Quarterly, Annual |
+| **Evidence Type** | Screenshot, Log, Policy, Config, Ticket |
+| **Testing Procedure** | How the auditor verifies the control |
+
+### Control Naming Convention
+
+```
+{CATEGORY}-{NUMBER}
+SEC-001 through SEC-NNN  → Security
+AVL-001 through AVL-NNN  → Availability
+CON-001 through CON-NNN  → Confidentiality
+PRI-001 through PRI-NNN  → Processing Integrity
+PRV-001 through PRV-NNN  → Privacy
+```
+
+### Workflow
+
+1. Select applicable TSC categories based on business needs
+2. Run `control_matrix_builder.py` to generate the baseline matrix
+3. Customize controls to match your actual environment
+4. Assign owners and evidence requirements
+5. Validate coverage — every selected TSC criterion must have at least one control
+
+---
+
+## Gap Analysis Workflow
+
+### Phase 1: Current State Assessment
+
+1. **Document existing controls** — inventory all security policies, procedures, and technical controls
+2. **Map to TSC** — align existing controls to Trust Service Criteria
+3. **Collect evidence samples** — gather proof that controls exist and operate
+4. **Interview control owners** — verify understanding and execution
+
+### Phase 2: Gap Identification
+
+Run `gap_analyzer.py` against your current controls to identify:
+
+- **Missing controls** — TSC criteria with no corresponding control
+- **Partially implemented** — Control exists but lacks evidence or consistency
+- **Design gaps** — Control designed but does not adequately address the criteria
+- **Operating gaps** (Type II only) — Control designed correctly but not operating effectively
+
+### Phase 3: Remediation Planning
+
+For each gap, define:
+
+| Field | Description |
+|-------|-------------|
+| Gap ID | Reference identifier |
+| TSC Criteria | Affected criteria |
+| Gap Description | What is missing or insufficient |
+| Remediation Action | Specific steps to close the gap |
+| Owner | Person responsible for remediation |
+| Priority | Critical / High / Medium / Low |
+| Target Date | Completion deadline |
+| Dependencies | Other gaps or projects that must complete first |
+
+### Phase 4: Timeline Planning
+
+| Priority | Target Remediation |
+|----------|--------------------|
+| Critical | 2-4 weeks |
+| High | 4-8 weeks |
+| Medium | 8-12 weeks |
+| Low | 12-16 weeks |
+
+---
+
+## Evidence Collection
+
+### Evidence Types by Control Category
+
+| Control Area | Primary Evidence | Secondary Evidence |
+|--------------|-----------------|-------------------|
+| Access Management | User access reviews, provisioning tickets | Role matrix, access logs |
+| Change Management | Change tickets, approval records | Deployment logs, test results |
+| Incident Response | Incident tickets, postmortems | Runbooks, escalation records |
+| Vulnerability Management | Scan reports, patch records | Remediation timelines |
+| Encryption | Configuration screenshots, certificate inventory | Key rotation logs |
+| Backup & Recovery | Backup logs, DR test results | Recovery time measurements |
+| Monitoring | Alert configurations, dashboard screenshots | On-call schedules, escalation records |
+| Policy Management | Signed policies, version history | Training completion records |
+| Vendor Management | Vendor assessments, SOC 2 reports | Contract reviews, risk registers |
+
+### Automation Opportunities
+
+| Area | Automation Approach |
+|------|-------------------|
+| Access reviews | Integrate IAM with ticketing (automatic quarterly review triggers) |
+| Configuration evidence | Infrastructure-as-code snapshots, compliance-as-code tools |
+| Vulnerability scans | Scheduled scanning with auto-generated reports |
+| Change management | Git-based audit trail (commits, PRs, approvals) |
+| Uptime monitoring | Automated SLA dashboards with historical data |
+| Backup verification | Automated restore tests with success/failure logging |
+
+### Continuous Monitoring
+
+Move from point-in-time evidence collection to continuous compliance:
+
+1. **Automated evidence gathering** — scripts that pull evidence on schedule
+2. **Control dashboards** — real-time visibility into control status
+3. **Alert-based monitoring** — notify when a control drifts out of compliance
+4. **Evidence repository** — centralized, timestamped evidence storage
+
+---
+
+## Audit Readiness Checklist
+
+### Pre-Audit Preparation (4-6 Weeks Before)
+
+- [ ] All controls documented with descriptions, owners, and frequencies
+- [ ] Evidence collected for the entire observation period (Type II)
+- [ ] Control matrix reviewed and gaps remediated
+- [ ] Policies signed and distributed within the last 12 months
+- [ ] Access reviews completed within the required frequency
+- [ ] Vulnerability scans current (no critical/high unpatched > SLA)
+- [ ] Incident response plan tested within the last 12 months
+- [ ] Vendor risk assessments current for all subservice organizations
+- [ ] DR/BCP tested and documented within the last 12 months
+- [ ] Employee security training completed for all staff
+
+### Readiness Scoring
+
+| Score | Rating | Meaning |
+|-------|--------|---------|
+| 90-100% | Audit Ready | Proceed with confidence |
+| 75-89% | Minor Gaps | Address before scheduling audit |
+| 50-74% | Significant Gaps | Remediation required |
+| < 50% | Not Ready | Major program build-out needed |
+
+### Common Audit Findings
+
+| Finding | Root Cause | Prevention |
+|---------|-----------|-----------|
+| Incomplete access reviews | Manual process, no reminders | Automate quarterly review triggers |
+| Missing change approvals | Emergency changes bypass process | Define emergency change procedure with post-hoc approval |
+| Stale vulnerability scans | Scanner misconfigured | Automated weekly scans with alerting |
+| Policy not acknowledged | No tracking mechanism | Annual e-signature workflow |
+| Missing vendor assessments | No vendor inventory | Maintain vendor register with review schedule |
+
+---
+
+## Vendor Management
+
+### Third-Party Risk Assessment
+
+Every vendor that accesses, stores, or processes customer data must be assessed:
+
+1. **Vendor inventory** — maintain a register of all service providers
+2. **Risk classification** — categorize vendors by data access level
+3. **Due diligence** — collect SOC 2 reports, security questionnaires, certifications
+4. **Contractual protections** — ensure DPAs, security requirements, breach notification clauses
+5. **Ongoing monitoring** — annual reassessment, continuous news monitoring
+
+### Vendor Risk Tiers
+
+| Tier | Data Access | Assessment Frequency | Requirements |
+|------|-------------|---------------------|-------------|
+| Critical | Processes/stores customer data | Annual + continuous monitoring | SOC 2 Type II, penetration test, security review |
+| High | Accesses customer environment | Annual | SOC 2 Type II or equivalent, questionnaire |
+| Medium | Indirect access, support tools | Annual questionnaire | Security certifications, questionnaire |
+| Low | No data access | Biennial questionnaire | Basic security questionnaire |
+
+### Subservice Organizations
+
+When your SOC 2 report relies on controls at a subservice organization (e.g., AWS, GCP, Azure):
+
+- **Inclusive method** — your report covers the subservice org's controls (requires their cooperation)
+- **Carve-out method** — your report excludes their controls but references their SOC 2 report
+- Most companies use **carve-out** and include complementary user entity controls (CUECs)
+
+---
+
+## Continuous Compliance
+
+### From Point-in-Time to Continuous
+
+| Aspect | Point-in-Time | Continuous |
+|--------|---------------|-----------|
+| Evidence collection | Manual, before audit | Automated, ongoing |
+| Control monitoring | Periodic review | Real-time dashboards |
+| Drift detection | Found during audit | Alert-based, immediate |
+| Remediation | Reactive | Proactive |
+| Audit preparation | 4-8 week scramble | Always ready |
+
+### Implementation Steps
+
+1. **Automate evidence gathering** — cron jobs, API integrations, IaC snapshots
+2. **Build control dashboards** — aggregate control status into a single view
+3. **Configure drift alerts** — notify when controls fall out of compliance
+4. **Establish review cadence** — weekly control owner check-ins, monthly steering
+5. **Maintain evidence repository** — centralized, timestamped, auditor-accessible
+
+### Annual Re-Assessment Cycle
+
+| Quarter | Activities |
+|---------|-----------|
+| Q1 | Annual risk assessment, policy refresh, vendor reassessment launch |
+| Q2 | Internal control testing, remediation of findings |
+| Q3 | Pre-audit readiness review, evidence completeness check |
+| Q4 | External audit, management assertion, report distribution |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Better Approach |
+|--------------|-------------|----------------|
+| Point-in-time compliance | Controls degrade between audits; gaps found during audit | Implement continuous monitoring and automated evidence |
+| Manual evidence collection | Time-consuming, inconsistent, error-prone | Automate with scripts, IaC, and compliance platforms |
+| Missing vendor assessments | Auditors flag incomplete vendor due diligence | Maintain vendor register with risk-tiered assessment schedule |
+| Copy-paste policies | Generic policies don't match actual operations | Tailor policies to your actual environment and technology stack |
+| Security theater | Controls exist on paper but aren't followed | Verify operating effectiveness; build controls into workflows |
+| Skipping Type I | Jumping to Type II without foundational readiness | Start with Type I to validate control design before observation |
+| Over-scoping TSC | Including all 5 categories when only Security is needed | Select categories based on actual customer/business requirements |
+| Treating audit as a project | Compliance degrades after the report is issued | Build compliance into daily operations and engineering culture |
+
+---
+
+## Tools
+
+### Control Matrix Builder
+
+Generates a SOC 2 control matrix from selected TSC categories.
+
+```bash
+# Generate full security matrix in markdown
+python scripts/control_matrix_builder.py --categories security --format md
+
+# Generate matrix for multiple categories as JSON
+python scripts/control_matrix_builder.py --categories security,availability,confidentiality --format json
+
+# All categories, CSV output
+python scripts/control_matrix_builder.py --categories security,availability,confidentiality,processing-integrity,privacy --format csv
+```
+
+### Evidence Tracker
+
+Tracks evidence collection status per control.
+
+```bash
+# Check evidence status from a control matrix
+python scripts/evidence_tracker.py --matrix controls.json --status
+
+# JSON output for integration
+python scripts/evidence_tracker.py --matrix controls.json --status --json
+```
+
+### Gap Analyzer
+
+Analyzes current controls against SOC 2 requirements and identifies gaps.
+
+```bash
+# Type I gap analysis
+python scripts/gap_analyzer.py --controls current_controls.json --type type1
+
+# Type II gap analysis (includes operating effectiveness)
+python scripts/gap_analyzer.py --controls current_controls.json --type type2 --json
+```
+
+---
+
+## References
+
+- [Trust Service Criteria Reference](references/trust_service_criteria.md) — All 5 TSC categories with sub-criteria, control objectives, and evidence examples
+- [Evidence Collection Guide](references/evidence_collection_guide.md) — Evidence types per control, automation tools, documentation requirements
+- [Type I vs Type II Comparison](references/type1_vs_type2.md) — Detailed comparison, timeline, cost analysis, and upgrade path
+
+---
+
+## Cross-References
+
+- **[gdpr-dsgvo-expert](../gdpr-dsgvo-expert/SKILL.md)** — SOC 2 Privacy criteria overlaps significantly with GDPR requirements; use together when processing EU personal data
+- **[information-security-manager-iso27001](../information-security-manager-iso27001/SKILL.md)** — ISO 27001 Annex A controls map closely to SOC 2 Security criteria; organizations pursuing both can share evidence
+- **[isms-audit-expert](../isms-audit-expert/SKILL.md)** — Audit methodology and finding management patterns transfer directly to SOC 2 audit preparation

package/content/design-system/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: design-system
+description: Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html converter to consume. Use before any markdown-html conversion. Triggers on first-run onboarding ("set up the brand", "configure markdown-html", "run onboarding"), on explicit reset ("reset the design system", "re-onboard"), and is checked by every converter via config_loader.py before rendering. Refuses to save if body-text contrast fails AA 4.5:1 or the output dir isn't writable. Precedence: project (./.markdown-html/) > global (~/.config/markdown-html/) > built-in defaults; MARKDOWN_HTML_NO_CONFIG=1 bypasses.
+version: 2.10.0
+author: Alireza Rezvani
+license: MIT
+tags: [design-system, brand-palette, wcag, onboarding, customization, markdown-html, css-variables, typography]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# Design System — Onboarding + Shared Brand Tokens
+
+The design-system skill is the **shared brand owner** for the markdown-html plugin. Run its onboarding once. Every converter (`md-document`, `md-review`, `md-slides`) reads the resulting config via `config_loader.py` and applies the same 12 CSS custom properties to its output. Without this, conversions render with placeholder defaults — technically functional but unbranded.
+
+This skill ships exactly three Python tools:
+
+1. **`onboard.py`** — interactive (or `--defaults` / `--set` / `--show` / `--reset`) wizard.
+2. **`config_loader.py`** — importable customization loader with project > global > defaults precedence and `MARKDOWN_HTML_NO_CONFIG=1` bypass.
+3. **`brand_palette_validator.py`** — WCAG-AA contrast checker + HSL palette deriver.
+
+All three are stdlib-only and contain no LLM calls (deterministic per Path-B discipline).
+
+## When to invoke
+
+| Symptom | Action |
+|---|---|
+| User says "convert this markdown to HTML" for the first time in this workspace | Run `python3 markdown-html/skills/design-system/scripts/onboard.py` |
+| `~/.config/markdown-html/design-system.json` doesn't exist OR `setup_completed_at` is null | Refuse conversion, surface onboarding |
+| User wants per-repo brand override | `python3 .../onboard.py --scope project` |
+| User wants to change a single field non-interactively | `python3 .../onboard.py --set brand.primary=#FF6B35` |
+| User wants to reset and re-onboard | `python3 .../onboard.py --reset` then re-run |
+| User wants zero-touch defaults (CI, ephemeral session) | `python3 .../onboard.py --defaults` |
+| Headless / containerized run that should ignore saved config | `MARKDOWN_HTML_NO_CONFIG=1 ...` |
+
+## Onboarding question set (10 questions)
+
+| # | Key | Choices / Validator | Default |
+|---|---|---|---|
+| 1 | `default_output_dir` | path; `os.access(parent, os.W_OK)` | `./markdown-html-out/` |
+| 2 | `brand.primary` | HEX `^#?[0-9a-fA-F]{6}$` | `#0A1628` |
+| 3 | `brand.accent` | HEX or blank (auto-derive) | derive from primary |
+| 4 | `typography.heading_font` | Google Font name (12 safe defaults) | `Inter` |
+| 5 | `typography.body_font` | Google Font name | `Inter` |
+| 6 | `design_style` | `editorial / technical / minimal / playful` | `technical` |
+| 7 | `code_theme` | `light / dark / auto` | `auto` |
+| 8 | `toc.behavior` | `sticky-sidebar / collapsible-top / inline / none` | `sticky-sidebar` |
+| 9 | `company_name` | string (may be empty) | `""` |
+| 10 | `logo_url` | URL or empty (base64-embedded at render) | `""` |
+
+## Hard rules
+
+1. **WCAG AA body-text contrast must pass.** `brand_palette_validator.validate()` runs after every change. Body text on bg must reach 4.5:1; link on bg must reach 4.5:1. If either fails, `onboard.py` refuses to save (exit code 4) and tells the user to pick a darker primary, blank `brand.bg`/`brand.text` to let derivation pick a safe pair, or override `brand.text` directly. Canon: WCAG 2.2 §1.4.3.
+2. **Output directory must be writable.** `onboard.py` walks up the path to find an existing ancestor and checks `os.W_OK`. Empty or unwritable path → exit code 3. The orchestrator's `output_path_resolver.py` honors the same rule per-conversion.
+3. **Customization must change behavior, not sit as decoration.** Every consumer (md-document, md-review, md-slides) must read the config and render differently when the user changes `design_style`, `brand.primary`, `code_theme`, or `toc.behavior`. Decorative-only fields fail the design discipline.
+4. **Precedence is fixed.** Project > global > defaults. The deep-merge preserves nested keys (e.g. you can override `brand.primary` in a project config without losing `typography.heading_font` from global).
+5. **Bypass env exists for a reason.** `MARKDOWN_HTML_NO_CONFIG=1` is for headless CI, ephemeral test containers, and the autoresearch-style evaluator loops. Never set it silently for an interactive user.
+
+## Derived 12-token palette
+
+Once the user's brand is captured, `brand_palette_validator.derive_palette()` produces 12 CSS custom properties stored under `derived_palette` in the same config file. Every converter inlines these into its `<style>` block.
+
+| Token | Purpose | Derivation |
+|---|---|---|
+| `--md-bg` | Document background | Primary if dark, near-neutral if vibrant |
+| `--md-surface` | Card / callout / blockquote background | Bg ± 4-6% luminance |
+| `--md-border` | Hairline dividers, table borders | Bg ± 8-12% luminance |
+| `--md-text` | Body text | Off-white on dark bg, near-black on light bg |
+| `--md-text-muted` | Captions, metadata, footers | `rgba(text, 0.68)` |
+| `--md-accent` | Primary CTA, callout headers, link emphasis | Primary if vibrant, hue-shifted lighter if dark |
+| `--md-accent-soft` | Accent backgrounds, hover states | `rgba(accent, 0.14)` |
+| `--md-code-bg` | Inline code, fenced block bg | Bg ± 4-5% luminance |
+| `--md-link` | Hyperlinks | Iteratively walked to reach 4.5:1 contrast on bg |
+| `--md-link-hover` | Hover state | Link ± 6-8% luminance |
+| `--md-success` | OK / approved / passed | Green anchored, luminance-matched |
+| `--md-warn` | Caution / nit / TODO | Amber anchored, luminance-matched |
+
+## Forcing-question library (Matt Pocock grill-with-docs pattern)
+
+One question per turn, recommended answer, canon citation.
+
+1. **What's your brand primary color?** Recommended: a HEX you already use in your product or docs — not a stock blue. Canon: Aarron Walter, *Designing for Emotion* (color carries brand affect).
+2. **Should accent be derived or set?** Recommended: derive on first run (hue-shift + lighten produces a coherent companion); set explicitly only if your brand kit specifies one. Canon: Adobe Spectrum, *Color Foundations*.
+3. **Editorial, technical, minimal, or playful?** Recommended: `technical` for engineering specs/reports, `editorial` for long-read narratives, `minimal` for sparse reference docs, `playful` for marketing/landing content. Canon: Ellen Lupton, *Thinking with Type* (style serves the rhetorical purpose).
+4. **Sticky-sidebar TOC, or inline?** Recommended: `sticky-sidebar` for documents over 800 words, `inline` for short reads. Canon: Nielsen-Norman, *Table of Contents Best Practices* (2023).
+5. **Save to global or per-project?** Recommended: global by default (consistent across your work); use `--scope project` only when this repo has a different brand. Canon: research-ops onboarding pattern, `research-ops/CLAUDE.md` §8.
+
+## Customization in use (worked example)
+
+```bash
+# First-run onboarding (interactive, walks all 10 questions)
+python3 markdown-html/skills/design-system/scripts/onboard.py
+
+# Zero-touch defaults for CI / first-test
+python3 .../onboard.py --defaults
+
+# Change just the primary color and design style
+python3 .../onboard.py --set brand.primary=#FF6B35 --set design_style=editorial
+
+# Per-repo override
+python3 .../onboard.py --scope project --set design_style=minimal
+
+# Reset and re-onboard
+python3 .../onboard.py --reset
+python3 .../onboard.py
+
+# Inspect the effective config (project > global > defaults)
+python3 .../config_loader.py --show
+python3 .../config_loader.py --status
+
+# Bypass saved config (returns DEFAULTS only)
+MARKDOWN_HTML_NO_CONFIG=1 python3 .../config_loader.py --show
+
+# Spot-check WCAG contrast before committing to a brand
+python3 .../brand_palette_validator.py --primary "#FF6B35" --accent "#00D4AA"
+```
+
+## Assumptions
+
+1. User has at least one brand HEX they want consistent across their HTML conversions.
+2. User accepts a 1-2 minute one-time setup.
+3. User is OK with Google Fonts as the typography source (CDN, no local font hosting).
+4. WCAG 2.2 AA is the accessibility floor (4.5:1 body, 3:1 large/UI). AAA (7:1) is out of scope.
+
+## Non-goals
+
+- Not a full design-token system (Style Dictionary, Theo). Twelve tokens, not a hundred.
+- Not a custom-font hosting solution. Google Fonts only.
+- Not a dark/light mode switcher in the converters. `code_theme: auto` handles the prefers-color-scheme case for syntax highlighting; layout palette is single-mode per onboarding.
+- Not an accessibility audit suite (use axe-core / pa11y for that). We enforce contrast only.
+- Does not transform existing CSS — the derived palette is injected into freshly generated HTML.
+
+## Distinct from
+
+- **`marketing/landing/skills/landing/scripts/brand_palette_validator.py`** — that script's `derive_palette()` produces 8 tokens shaped for hero-page rendering (`--navy`, `--teal`, `--card-bg`, `--card-border`). This script produces 12 tokens shaped for document rendering (sticky surface, hairline border, code bg, link, link-hover, success, warn). Same WCAG + HSL math, different token taxonomy.
+- **`research-ops/skills/clinical-research/scripts/onboard.py`** — same pattern (interactive + `--defaults`/`--set`/`--show`/`--reset`/`--scope`), different question set (clinical alpha/power/dropout vs. brand palette/typography/layout).
+
+## Output artifact
+
+`~/.config/markdown-html/design-system.json` (global) or `./.markdown-html/design-system.json` (project). JSON schema lives at `assets/design_system_schema.json`.
+
+## Anti-patterns (do not)
+
+- ❌ Skip onboarding and run a converter with placeholder defaults — output looks unbranded.
+- ❌ Pick a vibrant brand primary as `brand.bg` directly (low text contrast). Use it as accent instead.
+- ❌ Set `MARKDOWN_HTML_NO_CONFIG=1` silently for an interactive user — they'll wonder why their tokens disappeared.
+- ❌ Encode brand semantics in `derived_palette` outside the 12-token taxonomy. Add a new token only with a deliberate name + purpose + derivation rule.
+
+## References
+
+- WCAG 2.2 — §1.4.3 (contrast), §1.4.4 (resize), §1.4.11 (non-text contrast)
+- Aarron Walter — *Designing for Emotion* (A Book Apart)
+- Ellen Lupton — *Thinking with Type*
+- Adobe Spectrum — *Color Foundations*
+- Nielsen-Norman — *Table of Contents Best Practices* (2023)
+- research-ops onboarding pattern: `research-ops/CLAUDE.md` §8
+- Brand palette math source: `marketing/landing/skills/landing/scripts/brand_palette_validator.py`