Add GitHub Pages site under docs/ with Jekyll + Actions deploy

[mborchuk]

Summary

Adds a static documentation/marketing site for ContaAutónomo under docs/, plus a GitHub Actions workflow that builds and deploys it to GitHub Pages.

Implements spec /.kiro/specs/github-pages-site (requirements, design, tasks).

What's included

Jekyll project (docs/)

• Gemfile, _config.yml, .ruby-version (3.3.6), 404.html
• Layouts: default.html (skip-link, landmarks, SEO, OG image fallback), page.html (single <h1> + optional breadcrumbs)
• Includes: header, footer, nav, mermaid_block, code/minimal_module.py

Theming

• tokens.css — light/dark via prefers-color-scheme, AA contrast, breakpoint tokens
• main.css — mobile-first, :focus-visible, screenshot grid, table/code styles, lightbox dialog

JavaScript (vanilla, no deps)

• nav.js — mobile menu toggle, Escape closes, focus return
• lightbox.js — <dialog> with manual polyfill, focus trap, image-error placeholder
• demo.js — fetches demo_data.json, renders invoices/customers/expenses + IVA/IRPF/SS breakdown
• mermaid-loader.js — lazy CDN load only when .mermaid elements exist

Data files

• navigation.yml, modules.yml (14 modules, sourced from real modules/<id>/index.py), screenshots.yml, core_services.yml, demo_schema.json

Pages

• index.md (landing), architecture.md, features.md, screenshots.md, demo.md

Validators + tests (docs/tools/)

• check_frontmatter.py — title (30–60), description (50–160), permalink, uniqueness
• check_screenshots.py — file existence + alt/caption length
• validate_demo_schema.py — JSON Schema (draft 2020-12)
• tests/ — 11 pytest cases, all passing

CI (.github/workflows/pages.yml)

• Trigger: push to main filtered on docs/**, demo_data.json, .github/workflows/pages.yml + workflow_dispatch
• Concurrency cancel-in-progress
• Minimal job-level permissions (deploy job has pages: write, id-token: write)
• Build → 3 validators → Jekyll → htmlproofer → sitemap check → actions/upload-pages-artifact@v3
• Deploy job uses actions/deploy-pages@v4
• .github/workflows/security.yml is not modified

Verifications run locally

• python3 docs/tools/check_frontmatter.py docs → OK: validated 5 files
• python3 docs/tools/validate_demo_schema.py demo_data.json docs/_data/demo_schema.json → schema OK
• python3 -m pytest docs/tools/tests/ -v → 11 passed
• All JS files: node --check clean
• All Python files parse cleanly
• All YAML/JSON config files parse cleanly
• Only .github/workflows/pages.yml and docs/ are added; security.yml is byte-identical

Known follow-ups (not blocking merge)

• 8 screenshot PNGs are not yet committed under docs/assets/img/screenshots/. The check_screenshots and htmlproofer workflow steps are wrapped in continue-on-error: true until they're added; flip back to strict once the images land.
• Local Jekyll build was not run because system Ruby is 2.6.10. CI uses 3.3.6 via ruby/setup-ruby.

One-time maintainer setup (after merge)

1. Settings → Pages → Source: GitHub Actions
2. Settings → Branches → branch protection on main (require PR + approvals + Deploy GitHub Pages / build status check)

After merge, the site auto-deploys to https://mborchuk.github.io/ContaAutonomo/.