unaltraweb 0.3.0

data/docs/_documentation/en/50-faq.md

@@ -0,0 +1,33 @@
+---
+title: Frequently Asked Questions
+description: Common questions about unaltraweb sites.
+lang: en
+ref: faq
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- local-authors
+- site-designers
+- contributors
+- core-developers
+section: Reference
+weight: 920
+permalink: "/faq/"
+nav_title: FAQ
+---
+## Do content editors need Docker?
+
+No. Small edits can be done in GitHub. Docker is for local preview, tests and larger edits.
+
+## Does a child site need to copy layouts?
+
+No. Layouts, includes, Sass, plugins and scripts should come from the `unaltraweb` gem. Copy files only for deliberate local overrides.
+
+## Why use site profiles?
+
+Profiles choose a real build shape before Jekyll writes the site. They are not client-side previews.
+
+## Can one repository contain all profiles?
+
+The integration template does so it can test every profile. `new_web` creates real sites with one selected profile and only its required content paths.

data/docs/_pages/ca/index.md

@@ -0,0 +1,35 @@
+---
+title: unaltraweb
+description: Documentació de referència i exemples reals d'unaltraweb.
+layout: documentation-home
+lang: ca
+ref: home
+profiles: [unaltredocs]
+permalink: /ca/
+nav: false
+nav_title: Inici
+hero:
+  image: /assets/img/unaltraweb-docs-hero.svg
+  alt: Diagrama del flux de documentació d'unaltraweb.
+  cta_label: Comença
+  cta_url: /quick-start/
+---
+
+# unaltraweb
+
+`unaltraweb` és una plataforma Jekyll reutilitzable per a webs estàtiques acadèmiques, projectes de recerca, cursos, programari, manuals i documentació.
+
+El nom ve de l'expressió catalana `una altra web`: una altra web. Resumeix una necessitat habitual en el treball acadèmic: els membres del grup sovint necessiten una web més per a un curs, un projecte, un perfil personal, un manual o un espai públic de documentació.
+
+El sistema redueix manteniment duplicat centralitzant l'estil visual i les funcionalitats principals en una plataforma compartida. Llistats bibliogràfics, diagrames, figures, taules, resultats de recerca, navegació multilingüe i barres laterals de documentació es mantenen una vegada i es reutilitzen en webs personals, webs de projecte, materials docents i documentació tècnica.
+
+Usa aquest portal per entendre el model de contingut reutilitzable, triar el perfil adequat, executar el flux local amb Docker i documentar la sintaxi que va més enllà del Markdown estàndard.
+
+## Repositoris
+
+- Core: `dosquartsdedocs/unaltraweb`.
+- Starter i integració: `dosquartsdedocs/unaltraweb-template`.
+
+## Origen
+
+`unaltraweb` va començar a partir del tema Jekyll obert `al-folio` i s'està refactoritzant com a nucli reutilitzable propi per als llocs de `dosquartsdedocs`.

data/docs/_pages/en/index.md

@@ -0,0 +1,35 @@
+---
+title: unaltraweb
+description: Reference documentation and live examples for unaltraweb.
+layout: documentation-home
+lang: en
+ref: home
+profiles: [unaltredocs]
+permalink: /
+nav: false
+nav_title: Overview
+hero:
+  image: /assets/img/unaltraweb-docs-hero.svg
+  alt: Diagram of the unaltraweb documentation workflow.
+  cta_label: Get started
+  cta_url: /quick-start/
+---
+
+# unaltraweb
+
+`unaltraweb` is a reusable Jekyll platform for static academic, research project, course, software, manual and documentation websites.
+
+The name comes from Catalan `una altra web`: another website. It reflects a recurring need in academic work: group members often need one more website for a course, a project, a personal profile, a manual or a public documentation space.
+
+The system reduces duplicated maintenance by centralizing visual style and core features in one shared platform. Bibliography lists, diagrams, figures, tables, publication outputs, multilingual navigation and documentation sidebars are maintained once and reused across personal sites, project sites, course materials and technical documentation.
+
+Use this portal to understand the reusable content model, choose the right site profile, run the local Docker workflow and document syntax that goes beyond standard Markdown.
+
+## Repositories
+
+- Core: `dosquartsdedocs/unaltraweb`.
+- Starter and integration fixture: `dosquartsdedocs/unaltraweb-template`.
+
+## Lineage
+
+`unaltraweb` started from the open-source `al-folio` Jekyll theme and is being refactored into a self-owned reusable core for `dosquartsdedocs` sites.

data/docs/_pages/es/index.md

@@ -0,0 +1,35 @@
+---
+title: unaltraweb
+description: Documentación de referencia y ejemplos reales de unaltraweb.
+layout: documentation-home
+lang: es
+ref: home
+profiles: [unaltredocs]
+permalink: /es/
+nav: false
+nav_title: Inicio
+hero:
+  image: /assets/img/unaltraweb-docs-hero.svg
+  alt: Diagrama del flujo de documentación de unaltraweb.
+  cta_label: Empezar
+  cta_url: /quick-start/
+---
+
+# unaltraweb
+
+`unaltraweb` es una plataforma Jekyll reutilizable para sitios estáticos académicos, proyectos de investigación, cursos, software, manuales y documentación.
+
+El nombre viene del catalán `una altra web`: otra web. Resume una necesidad habitual en el trabajo académico: los miembros del grupo a menudo necesitan una web más para un curso, un proyecto, un perfil personal, un manual o un espacio público de documentación.
+
+El sistema reduce mantenimiento duplicado centralizando el estilo visual y las funcionalidades principales en una plataforma compartida. Listados bibliográficos, diagramas, figuras, tablas, resultados de investigación, navegación multilingüe y barras laterales de documentación se mantienen una vez y se reutilizan en webs personales, webs de proyecto, materiales docentes y documentación técnica.
+
+Usa este portal para entender el modelo de contenido reutilizable, escoger el perfil adecuado, ejecutar el flujo local con Docker y documentar la sintaxis que va más allá de Markdown estándar.
+
+## Repositorios
+
+- Core: `dosquartsdedocs/unaltraweb`.
+- Starter e integración: `dosquartsdedocs/unaltraweb-template`.
+
+## Origen
+
+`unaltraweb` empezó a partir del tema Jekyll abierto `al-folio` y se está refactorizando como núcleo reutilizable propio para los sitios de `dosquartsdedocs`.

data/docs/agents/action-prompts/00-start-site-session.txt

@@ -0,0 +1,10 @@
+Start or resume work in an `unaltraweb` website workspace.
+
+1. Read local `AGENTS.md` if present.
+2. If the workspace has no `_config.yml`, inspect `web://new-web-scaffolds`, then use `new_web` only after the target profile, title, baseurl, url, default language, and maintained languages are known or intentionally left blank.
+3. Inspect `web://site-context` or call `site_context`.
+4. Confirm the configured `unaltraweb.site_profile`, `language_policy`, languages, and enabled features before editing.
+5. Run or inspect `profile_check`, `content_inventory`, `content_approval_inventory`, `translation_plan`, `bibliography_inventory`, and `content_freshness_check`.
+6. Keep edits inside the website workspace. Do not treat chat history as durable project memory.
+7. For visible content changes, run `build_site` or the local Make equivalent before handoff when feasible.
+8. Do not commit or publish visible content changes until the human author has reviewed the served site in a browser and explicitly approved the rendered result.

data/docs/agents/action-prompts/05-create-new-web.txt

@@ -0,0 +1,5 @@
+Create a new unaltraweb website only after confirming the intended profile, title, URL/base URL, default language, and maintained languages.
+
+Use `new_web`, which reads only package-owned scaffold assets. Do not source a template from another checkout or arbitrary filesystem path. The operation preflights every managed path, rejects destination symlinks and differing files, and writes no website files when a collision is present during preflight. No-clobber descriptor writes prevent a raced file from being overwritten.
+
+After creation, inspect `profile_check`, edit the generated configuration and localized home pages, then run `site_check` and `build_site`.

data/docs/agents/action-prompts/10-content-update.txt

@@ -0,0 +1,9 @@
+Update one `unaltraweb` content item.
+
+1. Identify the profile and content type before editing: page, post, news item, project, output, chapter, documentation page, book, thesis, or `_data` record.
+2. Preserve front matter keys used for routing: `title`, `lang`, `ref`, `permalink`, `profiles`, `feature`, `section`, and `weight` when relevant.
+3. Draft and approve substantial content in the configured default language first. For multilingual content, keep `ref` stable across languages and do not silently update translations while the default-language source is still changing.
+4. Use `site_source_read` and its SHA-256 before `site_source_write`; review the default dry-run diff, then apply the exact CAS update. New files require `create_only=true`.
+5. Prefer small versionable edits over generated churn. Do not use these tools for bibliography, assets, workflows, Makefiles, layouts, plugins, Sass, or generated paths.
+6. Use `translation_plan` before publication to identify approved default-language content that still needs localization.
+7. Run `profile_check` and a build check when the edit changes navigation, links, or collection structure.

data/docs/agents/action-prompts/15-edit-default-content.txt

@@ -0,0 +1,8 @@
+Draft or revise default-language `unaltraweb` content.
+
+1. Read `language_policy`, `content_approval_inventory`, and the target file before editing.
+2. Work in the configured default language first. Do not translate parallel language files during drafting unless the user explicitly asks for a translation pass.
+3. Preserve `lang`, `ref`, `permalink`, `profiles`, `section`, `subsection`, `weight`, and other routing front matter.
+4. Use `content_status: draft`, `review`, or `approved` to make editorial state explicit. Only mark content as `approved` when the user or project rules make that approval clear.
+5. When meaning changes in approved default-language content, treat existing translations as stale and mention that `translation_plan` should be checked before publication.
+6. Run `profile_check`; run `build_site` when the edit changes navigation, layout, links, citations, or collection structure.

data/docs/agents/action-prompts/20-manual-teaching-materials.txt

@@ -0,0 +1,18 @@
+Create or revise teaching material for an `unaltremanual` site.
+
+1. Read the manual profile config and inventory `_chapters/<lang>/`, manual bibliography files, figures, tables, and downloadable resources.
+2. Read the site `AGENTS.md`, `context/writing-profile.md` when present, and `manual_authoring_capabilities`. Local writing-profile rules override the generic voice; the capability catalogue is the source of truth for component syntax and web/PDF compatibility.
+3. Work in the configured default language until the chapter or resource is approved. Use `translation_plan` only as a pre-publication localization checklist.
+4. Write for sequential learners with narrative pedagogical prose: clear chapter function, stable headings, connected paragraphs, examples, exercises or prompts when appropriate, and references where claims depend on literature. Diagnose paragraph function before sentence polish and prioritise this sequence when it fits the material: topic or reader goal; problem or question; arguments, evidence, and examples; discussion, alternatives, consequences, or limits; concrete closure or transition. Do not force every paragraph through every move. Use `##` and `###` for divisions exposed in the secondary TOC and `####` for a cohesive numbered local subsection that should stay out of that TOC. Never imitate `h4` with a standalone bold label and terminal period; a bold run-in belongs in the same paragraph it introduces.
+5. Use bullet lists for steps, criteria, inventories, or rubrics, but do not let lists replace the explanation of concepts, decisions, or transitions between theory and practice.
+6. Write only reader-facing, publishable body content. Never include chat replies, references to the user or their instructions, agent actions, drafting plans, approval states, `content_status` values, TODO markers, placeholders, or notes to the author in pages or chapters. Keep that material in `AGENTS.md`, `context/`, issues, or review notes.
+7. Select components because they improve the explanation, not for decoration. Use `Term` followed by `: Definition` for compact dictionary entries; caption every teaching figure; use `::: subfigures layout "Caption"` for a shared multi-panel comparison; and wrap every teaching table in `::: table "Caption"`. Check PDF compatibility in `manual_authoring_capabilities` before using a web-oriented layout.
+8. Use nested blockquotes selectively for teaching callouts: `>>` note or tip, `>>>` worked example, `>>>>` warning, `>>>>>` learning objectives, and `>>>>>>` caution or danger. Use them when the prose changes function, especially for concrete operational risks; do not use callouts merely to add color or place ordinary conceptual prose in consecutive boxes.
+9. Prefer versioned diagram sources rendered through `diavisuals`: `.mmd`/`.mermaid` for Mermaid and `.puml`/`.plantuml`/`.uml` for PlantUML. Do not use inline ```mermaid``` or ```plantuml``` fences for manual figures that should be numbered, captioned, reusable, or editable.
+10. For folder or file structures, prefer PlantUML `@startfiles` diagrams through `diavisuals` instead of plain text trees.
+11. For orientation material, keep broad explanations of how the manual works, how Moodle relates to the course, and how students should read chapters in chapter 0 or the configured orientation chapter rather than overloading the cover page.
+12. Keep web-only affordances separate from printable content when possible.
+13. Do not regenerate or overwrite author-edited diagram SVGs without asking when a matching `*.edited.svg` exists.
+14. Run `profile_check`, `manual_source_quality_check`, and `manual_editorial_quality_check`; run `build_site(site_profile="unaltremanual")` when structure, figures, bibliography, or navigation changed.
+15. When PDF output is enabled, run `manual_pdf_status` and `manual_pdf_build`, then ask the human author to review both browser and PDF output.
+16. Run `manual_pdf_publish` as a dry-run first. Do not perform a real PDF publication, commit, push, or site deployment without explicit human approval.

data/docs/agents/action-prompts/22-manual-style-audit.txt

@@ -0,0 +1,14 @@
+Review or revise the prose style of an `unaltremanual` chapter.
+
+1. Read `AGENTS.md`, the target chapter, `context/writing-profile.md` when present, and `manual_authoring_capabilities`.
+2. Diagnose section and paragraph function before sentence polishing. Each paragraph should mainly orient, establish a topic or problem, develop an argument, provide evidence or an example, discuss meaning or limits, guide a practical action, state a criterion, close an idea, or transition. Where appropriate, check the sequence topic or reader goal; problem or question; arguments, evidence, and examples; discussion or limits; concrete closure. Do not require every paragraph to contain every move.
+3. Prefer narrative pedagogical prose over executive-summary bullets. Keep lists for steps, criteria, inventories, or rubrics, but expand conceptual material into connected paragraphs.
+4. Audit heading depth as pedagogy, not formatting. `##` and `###` identify divisions exposed in the secondary TOC; `####` is a numbered local subdivision omitted from that TOC. Use `h4` for a cohesive minor unit with developed content. Replace standalone fake headings such as `**Source.**` with semantic `####` headings, or join a genuine bold run-in to the paragraph it introduces.
+5. Check callout semantics and restraint. The supported nested-blockquote convention is `>>` note or tip, `>>>` worked example, `>>>>` warning, `>>>>>` learning objectives, and `>>>>>>` caution or danger. Concrete operational risks belong in warnings; ordinary conceptual prose does not need a colored box.
+6. Check that theory and practice are connected: concepts should lead to decisions with data, software, maps, figures, synthesis, or assessment criteria.
+7. Treat every Markdown body line as publication copy. Reject references to the user, author instructions, agent actions, chat history, drafting status, approval workflow, internal field names, TODOs, placeholders, and notes that tell an editor what to write later.
+8. Review spelling, grammar, terminology, factual precision, paragraph cohesion, citations, cross-references, captions, and consistency with the official teaching guide. Report uncertainty outside the publishable body instead of inserting review notes into it.
+9. Check whether component choice serves the paragraph's pedagogical function. Definition lists are for compact terminology; callouts mark a genuine function change; `::: subfigures` expresses one multi-panel comparison; tables and figures require captions; reusable diagrams should be `.mmd`, `.mermaid`, `.puml`, `.plantuml`, or `.uml` sources rendered through `diavisuals`; folder/file trees should normally use PlantUML `@startfiles`. Report web/PDF mismatches.
+10. Do not invent official teaching-guide content, dates, assessment weights, learning outcomes, datasets, or policies. Mark those items for author verification when needed.
+11. Move general explanations of how the manual works, how Moodle relates to the course, and how students should read chapters into the orientation chapter rather than overloading the cover page.
+12. Run `manual_editorial_quality_check` and `profile_check`; run `build_site(site_profile="unaltremanual")` when structure, navigation, links, citations, or rendered content changed.

data/docs/agents/action-prompts/23-manual-structure-audit.txt

@@ -0,0 +1,17 @@
+Audit the structure and paragraph functions of an `unaltremanual` text against its reader goals.
+
+1. Read `AGENTS.md`, `context/writing-profile.md`, `web://manual-authoring-components`, the target text, and adjacent chapters before reviewing.
+2. Diagnose function before style. Assign each section and paragraph one primary job: orientation, topic, problem, concept, argument, evidence, example, technical decision, practical instruction, discussion, limitation, quality criterion, verification, warning, closure, or transition.
+3. Use this sequence diagnostically when appropriate: topic or reader goal; problem or question; arguments, evidence, and examples; discussion, alternatives, consequences, or limits; concrete closure or transition.
+4. Do not force every paragraph through every move. Flag missing setup, abrupt shifts, duplicated jobs, incompatible jobs combined in one paragraph, examples introduced before their purpose is clear, unsupported claims, and generic endings.
+5. Check the handoff between paragraphs. Replace vague bridge words with the concrete object, decision, result, or limitation that the next paragraph develops.
+6. Check whether a supported content component would improve the explanation: callout, definition list, captioned figure, subfigure layout, captioned table, Mermaid or PlantUML source, citation, code block, or equation. Do not add a component merely for decoration, and respect its web/PDF support boundary.
+7. Treat every body line as final publication copy. Put uncertainty and review findings in the audit response, never in the chapter body.
+8. Return a section map, paragraph-function map, issues ordered by reader impact, recommended actions, and remaining evidence or verification needs.
+
+Use this table for paragraph findings when useful:
+
+| Location | Primary job | Contribution to reader task | Evidence or example | Issue | Action |
+| --- | --- | --- | --- | --- | --- |
+
+Recommended actions are: keep, move, split, merge, compress, expand, rewrite, source, verify, or remove.

data/docs/agents/action-prompts/25-translation-prepublish.txt

@@ -0,0 +1,8 @@
+Prepare `unaltraweb` translations before publication.
+
+1. Read `language_policy` and `translation_plan` first.
+2. Translate only from default-language sources whose editorial status is approved.
+3. Keep `ref` identical across languages and set the translated file's `lang` to the target language.
+4. Preserve citations, bibliography keys, figure references, tables, callout semantics, links, code, and data field names unless the target language requires visible prose changes.
+5. Mark translated files with an explicit translation state, for example `translation_status: translated` or `translation_status: needs_review`, following local project rules.
+6. After translation, run `profile_check`, `translation_plan`, and `build_site` when feasible.

data/docs/agents/action-prompts/30-project-site-update.txt

@@ -0,0 +1,7 @@
+Update an `unaltreprojecte` research project site.
+
+1. Inspect project pages, `_outputs/`, `_projects/`, `_data/team.yml`, `_data/repositories.yml`, publications, resources, and news.
+2. Keep project communication concrete: funder/project identity, outputs, datasets, reports, maps, repositories, team roles, and dated news.
+3. Preserve DOI, GitHub, documentation, dataset, and download links exactly unless a verified replacement is provided.
+4. For publication or output claims, add or update bibliography entries only from verified metadata.
+5. Run `profile_check` and `build_site(site_profile="unaltreprojecte")` when navigation, outputs, team, or resources changed.

data/docs/agents/action-prompts/40-documentation-update.txt

@@ -0,0 +1,7 @@
+Update an `unaltredocs` documentation page.
+
+1. Inspect `_documentation/<lang>/`, `section`, `subsection`, `weight`, `documentation_profiles`, and version metadata.
+2. Prefer task, reference, troubleshooting, and operational clarity over linear textbook prose.
+3. Keep examples executable or clearly marked as illustrative. Do not invent commands or config keys.
+4. Preserve stable permalinks and cross-language `ref` values.
+5. Run `profile_check` and `build_site(site_profile="unaltredocs")` when documentation navigation or examples changed.

data/docs/agents/action-prompts/50-bibliography-entry.txt

@@ -0,0 +1,7 @@
+Add or revise bibliography for an `unaltraweb` site.
+
+1. Start with `bibliography_inventory` and check duplicate citekeys.
+2. Add entries only from author-provided BibTeX, DOI metadata, Zotero/exported metadata, or another verified source.
+3. Do not invent authors, titles, venues, years, DOIs, citation counts, quartiles, or metric fields.
+4. Use `bibliography_add_entry` for appends under `_bibliography/`; use replacement only after explicit approval when a citekey already exists.
+5. After bibliography changes, run `bibliometrics_check` or explain why the heavier check was not run.

data/docs/agents/action-prompts/60-bibliometrics-refresh.txt

@@ -0,0 +1,7 @@
+Refresh static bibliometrics for an `unaltraweb` site.
+
+1. Inspect `bibliography_inventory`, `web://bibliometrics`, `_data/metrics.yml`, `_data/metrics-overrides.yml`, and diagnostics under `tmp/` if present.
+2. Use `bibliometrics_check` for offline validation before networked updates.
+3. Use `bibliometrics_update` only when the author expects versionable bibliography and `_data/metrics.yml` changes.
+4. Use `bibliometrics_fetch_scimago` or `bibliometrics_update(fetch_scimago=True)` when Scimago cache refresh is required.
+5. Keep local caches and diagnostics unversioned; report unmatched or uncertain entries instead of forcing dubious matches.

data/docs/agents/action-prompts/70-build-and-review.txt

@@ -0,0 +1,12 @@
+Build and review an `unaltraweb` site change.
+
+1. Run `site_doctor` and `site_check`; resolve distribution, scaffold, profile, freshness, computation, capture, bibliography, and editorial failures before building.
+2. When `site_check` reports a required companion gate, run the selected provider check and retain its verifiable `.unaltraweb/receipts/<provider>.json`; never substitute a caller-provided success flag.
+3. Render stale computation or capture artefacts explicitly, preserving edited SVG overrides, then rerun their checks.
+4. Run `build_site`, passing `site_profile` when reviewing a specific profile override.
+5. Review the `html_audit` returned by a successful `build_site`; resolve broken local targets/fragments and document accessibility findings before previewing.
+6. If the project-owned preview is already running, call `http_check` with key local paths. Never supply or probe an arbitrary origin.
+7. For visual or browser-level checks, use the consumer site's existing Playwright/render-smoke Make targets rather than inventing a new server workflow.
+8. For visible content changes, start or reuse the local `make serve` preview and ask the human author to review the rendered site in their browser.
+9. Do not commit or publish content changes until the human author explicitly approves that served preview.
+10. Summarize build failures with the relevant target, return code, timeout state, and the bounded actionable stderr/stdout.

data/docs/agents/manual-authoring-components.md

@@ -0,0 +1,255 @@
+# Manual authoring components
+
+This is the component contract for MCP agents drafting or reviewing `unaltremanual` content. Read it together with the consumer site's `context/writing-profile.md`.
+
+## Paragraph development
+
+Diagnose paragraph function before polishing sentences. A paragraph should normally have one primary job and, when the material warrants it, develop this sequence:
+
+1. Name the topic, object, or reader goal.
+2. Establish the problem, question, uncertainty, or decision.
+3. Develop the explanation through arguments, verified evidence, concrete examples, or worked operations.
+4. Discuss meaning, alternatives, conditions, consequences, or limitations.
+5. Close with a concrete takeaway, quality criterion, verification step, or transition.
+
+Do not force every paragraph to contain all five moves. Use the sequence to diagnose missing logic. Improve paragraph structure before sentence style, separate evidence from interpretation, and do not invent examples or specificity merely to make prose appear concrete.
+
+## Heading levels
+
+Use heading levels semantically:
+
+```markdown
+## Numbered section
+### Numbered subsection
+#### Numbered fourth-level subsection
+```
+
+All three levels receive hierarchical numbers in the manual body. The secondary page TOC contains only `h2` and `h3`; `h4` remains a numbered local subdivision so the rail stays concise. Use `####` when a minor unit develops a cohesive idea, source, case, example, or operation through its own paragraph or paragraphs. Do not imitate a heading with a standalone bold phrase such as `**Source.**`; keep bold run-ins in the same paragraph they introduce.
+
+## Callouts
+
+Nested blockquote depth selects the callout type. The browser inserts the localized label, so do not repeat it manually.
+
+```markdown
+> Ordinary quotation
+
+>> Note or tip
+
+>>> Worked example
+
+>>>> Warning
+
+>>>>> Learning objectives
+
+>>>>>> Caution or danger
+```
+
+Web and PDF rendering use the same callout type and localized label. The PDF uses a compact, breakable framed box so multi-paragraph notes and objective lists can continue across pages; review both formats for fit and emphasis.
+
+Use `>>>>>` learning objectives sparingly, normally once after a short chapter or major-section introduction. They should orient the section after the reader has enough context, not replace the opening explanation, and they should not recur as mid-section reminders.
+
+## Definition lists
+
+Use definition lists for compact terminology that benefits from a dictionary-like presentation:
+
+```markdown
+Spatial reference system
+: Rules and parameters used to interpret coordinates in a defined spatial framework.
+```
+
+The web renders the term with a colon and the definition as an indented entry. The PDF renders the same relationship as an indented description list. Definitions should support explanatory prose, not replace it.
+
+## Figures
+
+Use an explicit Markdown title as the caption:
+
+```markdown
+![Accessible description](assets/img/map.png "Distribution of the indicator by municipality")
+```
+
+Every teaching figure needs meaningful alt text and a caption. The manual numbers figures automatically on the web; the same image and caption are available to the PDF builder.
+
+When the same width works on both supports, narrow and centre the complete figure container without setting a fixed height:
+
+```markdown
+![Project folders](assets/diagrams/folders.puml "Recommended project structure"){: data-figure-width="22rem"}
+```
+
+`data-figure-width` is a compatible shared fallback. When the web and printed page need different visible sizes, declare them independently:
+
+```markdown
+![Text-bearing map](assets/img/map.svg "Distribution by municipality"){: data-figure-width-web="44rem" data-figure-width-pdf="82%"}
+```
+
+The web value accepts a CSS width and remains limited by the reading column. The PDF value accepts a Pandoc length or percentage. Optional `data-figure-height-web` and `data-figure-height-pdf` values act as maximum constraints; width and height are always combined with the intrinsic aspect ratio, so the image is not stretched. Keep height automatic unless the support imposes a real limit.
+
+After inserting or regenerating a text-bearing SVG figure or diagram, run `manual_source_quality_check`. It estimates the smallest visible SVG text at the declared web and PDF sizes, compares it with the surrounding body text, and returns separate suggested widths. Raster images do not expose dependable text metrics; use SVG for charts and diagrams when possible, and still inspect both rendered supports at final size.
+
+For multilingual manuals, reference the default-language visual with an unsuffixed logical name. Add `.<lang>` immediately before the complete suffix only when the visual itself needs translation:
+
+```text
+map.svg              # default-language source
+map.ca.svg           # Catalan static variant
+boxplot.ca.qmd       # Catalan computation source
+quarterly.ca.vl.json # Catalan Vega-Lite source
+flow.ca.mmd          # Catalan Mermaid source
+folders.ca.puml      # Catalan PlantUML source
+```
+
+Web and PDF first try the requested language and fall back to the unsuffixed default source when that variant is absent. If a localized source exists but its declared output is absent, stale, or invalid, fix that source lifecycle rather than silently using the default output. Localized computation and Vega sources must declare distinct localized outputs.
+
+## Figure layouts
+
+Use `subfigures` when panels form one direct comparison or explanation, such as before/after states, controlled alternatives, a short sequence, or complementary views that the reader needs to inspect together:
+
+```markdown
+::: subfigures a+b/c "Comparison of source, intermediate result, and final map"
+![Source](assets/img/source.png "Source table")
+![Intermediate](assets/img/intermediate.png "Joined layer")
+![Result](assets/img/result.png "Final thematic map")
+:::
+```
+
+`+` places panels in one row and `/` starts a new row. Prefer compact layouts such as `a+b` or `a+b/c`, write one caption that states the shared comparison, and give each panel a specific caption. This is a high-value teaching device when juxtaposition carries the argument, but it should remain selective: do not group images only because they share a topic, and avoid consecutive multi-panel figures that reduce emphasis or make evidence too small. Web and PDF preserve the declared rows, panel labels and captions; always inspect dense layouts at the final page size.
+
+## Tables
+
+Every teaching table must use a captioned block:
+
+```markdown
+::: table "Checks before joining a table to a layer"
+| Check | Criterion |
+| --- | --- |
+| Key | Unique and stored with the same type |
+| Coverage | Expected territories are represented |
+:::
+```
+
+Bare pipe tables fail `manual_source_quality_check`. Captioned tables are numbered on the web and converted to Pandoc tables in the PDF.
+
+## Diagrams
+
+Store reusable sources under `assets/diagrams/` and reference them as captioned images:
+
+```markdown
+![Processing flow](assets/diagrams/flow.mmd "Processing flow from source to result")
+![Project folders](assets/diagrams/folders.puml "Recommended project structure")
+```
+
+Use Mermaid `.mmd` for flows and PlantUML `.puml` or `.plantuml` for structured diagrams. Prefer PlantUML `@startfiles` for file trees. `diavisuals` generates the SVG; preserve an existing `*.edited.svg` unless the author explicitly approves replacement. Do not use inline Mermaid or PlantUML fences in manuals.
+
+## Static Vega visualizations
+
+Store Vega-Lite specifications as `*.vl.json` and raw Vega specifications as `*.vg.json`. Declare each source exactly once in `.vegavisuals.yml`, including its generated output, then reference the source as a normal captioned image:
+
+```markdown
+![Quarterly totals](assets/charts/quarterly.vl.json "Quarterly totals"){: data-figure-width-web="42rem" data-figure-width-pdf="78%"}
+```
+
+The web and PDF builders resolve the source through the manifest and use the same declared output. A source used as a web image must produce SVG or PNG; prefer SVG for web/PDF parity. Declare non-source files through manifest `inputs`; project-relative static `data.url` references in strict JSON specifications are discovered recursively as well. Receipt verification requires that exact union and rejects remote, dynamic, absolute, or escaping data URLs. Render with `make visualization-render`, commit the specification, inputs, output, manifest, and `.vegavisuals.lock.json`, then run the companion `visualization_check` so the provider publishes its verifiable receipt. Do not publish while the check or receipt verification reports stale, missing, unmanaged, modified, or hash-mismatched output. Reference a generated output directly when one source intentionally has multiple render variants.
+
+## Web captures
+
+Use a versioned `.capture.yml` recipe when a teaching figure must show a rendered website. The recipe stores a local preview path, viewport, theme, waits, declared inputs, and CSS selectors for annotations. Rendering creates:
+
+```text
+page.capture.yml
+page.capture.png
+page.capture.svg
+page.capture.edited.svg  # optional author-owned override
+```
+
+Reference `page.capture.yml` as the captioned image source. Jekyll and the PDF builder prefer `page.capture.edited.svg` when it exists, otherwise `page.capture.svg`. The PNG is the untouched browser capture; annotations remain editable vector layers in the self-contained SVG. Never overwrite an edited SVG without approval, and do not publish while `web_capture_check` reports it stale.
+
+## Computed figures
+
+Use a computation source in `mode: figure` when a chapter must show a figure produced by R or Python code. Store the source under a configured `source_roots` directory (for example `assets/quarto/`), declare its outputs, and reference the source the same way you reference a diagram:
+
+```markdown
+![Alt text](assets/quarto/data-visualization/boxplot.qmd "Caption"){: data-figure-width-web="48rem" data-figure-width-pdf="88%"}
+```
+
+The source declares `mode: figure` and its generated assets:
+
+```yaml
+---
+unaltraweb_compute:
+  engine: r
+  mode: figure
+  outputs:
+    - assets/img/data-visualization/boxplot-housing.svg
+---
+```
+
+Run `manual_computation_status` and explicitly render stale figures with `manual_computation_render_figures` before building. `site_check` prevents package-scaffolded build/test/serve runs while generated outputs are stale; only the internal capture preview bypasses that gate so it can render the stale capture itself. Jekyll then rewrites the source reference to the declared output. An author-owned override named like the output with `.edited.svg` (for example `boxplot-housing.edited.svg`) wins over the regenerated figure and is never overwritten. Keep figure outputs deterministic: regenerate them from the source instead of editing the generated SVG, and ask before replacing an existing `.edited.svg`.
+
+## Citations, code, and math
+
+Use verified bibliography keys:
+
+```liquid
+{% cite sourceKey %}
+{% cite firstKey secondKey %}
+```
+
+Bibliographic citations, external URLs, and internal links are separate semantic categories in both outputs: citations use pink, external links use the external-link color, and links to headings or numbered equations use the internal-link color. Give headings stable explicit identifiers when another passage links to them:
+
+```markdown
+## Normalization {#normalization}
+
+See [the normalization criteria](#normalization) and the [OGC standards](https://www.ogc.org/).
+```
+
+Use ordinary fenced code with an explicit language. Rouge highlights recognized web code and the PDF renderer uses `listings`; inline code remains monospaced and visually distinct in both. The PDF guarantees language-specific highlighting, headers, and line numbers for `bash`, `shell`, `sh`, `sql`, `python`, and `r`. Use `url` for URLs or decomposed web requests, `spreadsheet` for spreadsheet formulas, and `filetree` for short file or directory listings; these semantic fences receive localized headers and dedicated highlighting on web and PDF. Wrap exactly one fence in `::: listing "Descriptive caption"` and `:::` when it needs a localized number, visible caption, and PDF index entry. Plain, unlabelled, and unsupported fences render as unnumbered verbatim without a header. Long PDF lines wrap within the printable page.
+
+For mathematics in Markdown sources, use single dollar delimiters for inline expressions and double dollar delimiters on separate lines for displayed equations. Displayed equations are numbered by default on the web and in the PDF:
+
+```markdown
+The density is $D_i=P_i/A_i$ for territory $i$.
+
+$$
+D_i = \frac{P_i}{A_i}
+\label{eq:density}
+$$
+
+Equation $\eqref{eq:density}$ defines density.
+```
+
+Add a stable `eq:` label inside a display block when the text needs to refer to it, then place `\eqref` inside inline-math delimiters so MathJax and LaTeX follow the same source. When a displayed expression explicitly does not need a number, opt out with `equation*`:
+
+```markdown
+\begin{equation*}
+\bar{x}_w = \frac{\sum_i w_i x_i}{\sum_i w_i}
+\end{equation*}
+```
+
+Do not place a label inside `equation*`, because an unnumbered expression has no stable equation number to retrieve. Do not mark mathematical variables as inline code: `` `P_i` `` renders literally instead of typesetting the subscript. Do not use `\(...\)` directly in Markdown sources because Kramdown consumes those backslashes before MathJax runs.
+
+## Bibliographies
+
+Store manual entries in `_bibliography/manual.bib` and cite them with `{% cite key %}`. The manual profile sorts the general bibliography and chapter reference lists alphabetically by contributor name, then year and title. Set `manual_references: true` on a chapter when it needs a references section.
+
+The web keeps access links compact: DOI and URL text are removed only from the visible reference line and remain available through DOI/LINK buttons and the expandable citation panel. The PDF has no interactive controls, so it prints DOI and URL text in both the general bibliography and each requested chapter bibliography. Do not remove access fields from BibTeX or use a no-access CSL to change the web presentation.
+
+## Web-only components
+
+Tabs, details, interactive charts and maps, galleries, audio, video, and arbitrary Liquid figure includes can work in the browser but do not have general PDF parity. An assistant must not introduce them into a PDF-enabled manual without stating the limitation and reviewing both outputs.
+
+## Executable sources
+
+When a `.qmd`, `.Rmd`, `.R`, `.py`, or `.ipynb` source owns a chapter, edit that source rather than its generated `.md`. Keep one R or Python engine per source, declare non-code inputs, render explicitly, and review source, Markdown, figures, and `.unaltraweb/computations.lock.json` together. Never publish while `manual_computation_check` reports stale output. For single figures, prefer `mode: figure` sources referenced from Markdown (see "Computed figures" above) instead of chapter-mode sources; render them explicitly with `manual_computation_render_figures` so each figure remains reproducible on its own.
+
+## Required checks
+
+Run these checks after drafting or structural revision:
+
+```text
+manual_source_quality_check
+manual_editorial_quality_check
+manual_computation_check when executable sources exist
+visualization_check when .vegavisuals.yml exists
+build_site
+manual_pdf_build when PDF output is enabled
+```
+
+All body content must remain publishable. Keep author instructions, uncertainty, review notes, workflow status, and unresolved editorial decisions outside pages and chapters.