# Ownership Boundaries (v1.x) `al-folio` is a starter kit. Runtime/component ownership lives in gems. This file is the authoritative **area-to-gem** table. For how the pieces connect at runtime — the wrapper/tag/gem delegation map, silent feature gating, the v1 config contract — see [`ARCHITECTURE.md`](ARCHITECTURE.md). For the short agent entry point, see [`AGENTS.md`](../AGENTS.md). ## Runtime ownership - `al-folio` (starter): example content, wiring, docs, integration harness. - `al_folio_core`: shared layouts/includes/runtime primitives and upgrade contracts. - `al_folio_distill`: Distill templates/runtime assets. - `al_cookie`: cookie consent runtime assets and consent logic. - `al_icons`: icon runtime loading (Font Awesome, Academicons, Scholar Icons). - `al_search`: search runtime payload (`ninja-keys`, search setup/hotkey assets). - Other `al-*` gems: feature-specific assets, tags, filters, and runtime behavior. ## Bundled v1 plugin routing Use this table before opening or reviewing a PR: | Area | Owning repo/gem | | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Base layouts, shared includes, publication card layout, repository cards, style/runtime primitives, upgrade contracts | `al-org-dev/al-folio-core` / `al_folio_core` | | CV data rendering and CV layouts | `al-org-dev/al-folio-cv` / `al_folio_cv` | | Distill layouts, tags, and Distill runtime assets | `al-org-dev/al-folio-distill` / `al_folio_distill` | | Bootstrap compatibility CSS/JS during the v1 transition window | `al-org-dev/al-folio-bootstrap-compat` / `al_folio_bootstrap_compat` | | Upgrade audit/report/codemods | `al-org-dev/al-folio-upgrade` / `al_folio_upgrade` | | Icons and icon-library loading | `al-org-dev/al-icons` / `al_icons` | | Search UI/runtime | `al-org-dev/al-search` / `al_search` | | Publication/citation helper logic | `al-org-dev/al-citations` / `al_citations` | | External post ingestion | `al-org-dev/al-ext-posts` / `al_ext_posts` | | Analytics providers | `al-org-dev/al-analytics` / `al_analytics` | | Comments providers | `al-org-dev/al-comments` / `al_comments` | | Cookie consent UI/runtime | `al-org-dev/al-cookie` / `al_cookie` | | Image/lightbox helpers | `al-org-dev/al-img-tools` / `al_img_tools` | | Math/TikZ runtime integration | `al-org-dev/al-math` / `al_math` | | Chart runtime integration | `al-org-dev/al-charts` / `al_charts` | | Newsletter form integration | `al-org-dev/al-newsletter` / `al_newsletter` | | Right-to-left languages: document direction, RTL styling | `al-org-dev/al-rtl` / `al_rtl` | | Email obfuscation and click-to-copy addresses | `al-org-dev/al-email-protect` / `al_email_protect` | | marimo notebook embeds and runnable Python snippets | `al-org-dev/al-marimo` / `al_marimo` | Local site overrides are still valid **in your own site**. A site created from this template may define `_layouts/.liquid`, `_includes/.liquid`, `_sass/*.scss`, or site-specific plugins when the customization is only for that site. Shared runtime fixes should be ported to the owning plugin instead. When a site keeps local overrides of plugin-owned files, run `bundle exec al-folio upgrade overrides audit`. Commit `.al-folio-overrides.yml` after review so future plugin gem updates can flag upstream changes to shadowed files. This does **not** apply to the `alshedivat/al-folio` starter repo itself, which must not contain those directories — `npm run lint:style-contract` enforces that boundary. See [local overrides: your site vs. this repo](ARCHITECTURE.md#local-overrides-your-site-vs-this-repo) for the distinction and its current caveat. Plugin releases are versioned and published independently on RubyGems. A plugin patch release does not require a new starter release unless the starter wiring, dependency pins, lockfile/image metadata, docs, or test fixtures need to change. ## Plugin naming convention - Theme-coupled plugins: - GitHub repo: `al-folio-` - gem/plugin id: `al_folio_` - Reusable plugins: - GitHub repo: `al-` or neutral name - gem/plugin id aligned with plugin namespace - Third-party non-`al-*` plugins are valid ecosystem plugins and may be featured. ## Featured vs bundled plugins - `featured`: listed in docs/catalog with metadata and compatibility, but not required in starter dependencies. - `bundled`: included in starter wiring (`Gemfile` + `_config.yml` plugin list) and shipped by default. Use [`_data/featured_plugins.yml`](../_data/featured_plugins.yml) as the catalog source of truth. ## Minified asset policy - Use pinned CDN assets (with SRI) for stable standalone third-party libraries. - Keep vendored release-time artifacts (with provenance) only where ownership needs complex runtime/module graphs (for example: `al_search`, `al_folio_distill`). - Do not add install-time network fetches in `gem install` / `bundle install` paths. ## Test ownership - `al-folio` tests: - Visual regression/parity (`test/visual/**`) - Cross-gem integration checks (plugin toggles, compat wiring, upgrade smoke tests) - Starter wiring contracts only - Gem-local tests (`al-folio-core`, `al-folio-distill`, `al-*`): - Component correctness (tags, filters, generators) - Runtime asset packaging contracts - Feature edge cases - Migration/upgrade contract logic in the owning gem ## Prohibited pattern - Do not duplicate gem-owned component correctness tests in `al-folio`. - Do not add local starter copies of gem-owned runtime files unless intentionally overriding behavior. - Do not leave intentional local overrides untracked; acknowledge them with `bundle exec al-folio upgrade overrides accept`. ## PR triage playbook - If a PR changes starter wiring/docs/content/tests only: keep it in `al-folio`. - If a PR changes gem-owned runtime/component behavior: redirect/port to the owning gem repo. - If a PR introduces a feature without an owner: - create a plugin proposal issue - recommend a standalone plugin repo - close/redirect the starter PR with references.