@dataimago/css 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/quarto/dataimago-light.scss

@@ -0,0 +1,327 @@
+// @dataimago/css@0.1.0-alpha.20 dist/quarto/dataimago-light.scss · sha256:042fa6f08f6042f38c8014ce106859ce69d2531da3601e90be98270e3a6053ef · generated from tokens; do not edit · restore: npx -p @dataimago/css@0.1.0-alpha.20 dataimago-sync
+// dataimago light theme for Quarto 1.8 — generated from the design tokens (tools/formats/quarto.mjs).
+// Bootstrap Sass variables are compile-time sRGB; runtime colours come from the custom properties below.
+
+/*-- scss:defaults --*/
+$body-bg: #ededeb !default;
+$body-color: #14140f !default;
+$headings-color: #14140f !default;
+$navbar-bg: #ededeb !default;
+$link-color: #434739 !default;
+$link-hover-color: #363a2e !default;
+$code-color: #1f618d !default;
+$code-bg: #faf2e3 !default;
+$border-color: #888785 !default;
+$font-family-sans-serif: Noto Sans, Fira Sans, system-ui, sans-serif !default;
+$font-family-monospace: JetBrains Mono, SF Mono, Monaco, Inconsolata, monospace !default;
+$headings-font-family: Josefin Sans, system-ui, sans-serif !default;
+$headings-font-weight: 500 !default;
+$h2-font-size: 1.875rem !default;
+
+/*-- scss:rules --*/
+// ── Design tokens (contract custom properties) ───────────────────────
+:root {
+  --color-palette-ink-50: #f5f5f4;
+  --color-palette-ink-100: #e7e5e4;
+  --color-palette-ink-200: #d6d3d1;
+  --color-palette-ink-300: #a8a29e;
+  --color-palette-ink-400: #78716c;
+  --color-palette-ink-500: #57534e;
+  --color-palette-ink-600: #44403c;
+  --color-palette-ink-700: #292524;
+  --color-palette-ink-800: #1c1917;
+  --color-palette-ink-900: #0c0a09;
+  --color-palette-stone-50: #f7f7f6;
+  --color-palette-stone-100: #ededeb;
+  --color-palette-stone-200: #dcdcda;
+  --color-palette-stone-300: #c1c1bf;
+  --color-palette-stone-400: #a0a0a0;
+  --color-palette-stone-500: #7c7c7c;
+  --color-palette-stone-600: #5e5e5c;
+  --color-palette-stone-700: #424240;
+  --color-palette-stone-800: #292927;
+  --color-palette-stone-900: #14140f;
+  --color-palette-forest-50: #f0f1ed;
+  --color-palette-forest-100: #dde0d4;
+  --color-palette-forest-200: #bdc4ad;
+  --color-palette-forest-300: #98a384;
+  --color-palette-forest-400: #7e8a6b;
+  --color-palette-forest-500: #5e6749;
+  --color-palette-forest-600: #4d5640;
+  --color-palette-forest-700: #434739;
+  --color-palette-forest-800: #363a2e;
+  --color-palette-forest-900: #1f2218;
+  --color-palette-paper-50: #fefdfb;
+  --color-palette-paper-100: #fdf9f2;
+  --color-palette-paper-200: #faf2e3;
+  --color-palette-paper-300: #f5e8cf;
+  --color-palette-paper-400: #edd9b3;
+  --color-palette-paper-500: #e0c088;
+  --color-palette-copper-50: #fdf4ee;
+  --color-palette-copper-100: #fbe5d1;
+  --color-palette-copper-200: #f6c79c;
+  --color-palette-copper-300: #f0a467;
+  --color-palette-copper-400: #ea8441;
+  --color-palette-copper-500: #d46820;
+  --color-palette-copper-600: #b55017;
+  --color-palette-copper-700: #913d15;
+  --color-palette-copper-800: #753318;
+  --color-palette-copper-900: #612b16;
+  --color-palette-accent-50: #f0f8fc;
+  --color-palette-accent-300: #3498DB;
+  --color-palette-accent-400: #2980B9;
+  --color-palette-accent-500: #1f618d;
+  --color-palette-accent-600: #154d6f;
+  --color-palette-accent-700: #0f3a52;
+  --color-palette-presentation-blue-50: #f0f8fc;
+  --color-palette-presentation-blue-500: #3498DB;
+  --color-palette-presentation-blue-600: #2980B9;
+  --color-palette-presentation-blue-700: #1f618d;
+  --color-functional-success: #27AE60;
+  --color-functional-warning: #F39C12;
+  --color-functional-error: #E74C3C;
+  --color-functional-info: #3498DB;
+  --transition-quick: 0.15s ease;
+  --transition-standard: 0.25s ease-in-out;
+  --transition-smooth: 0.35s ease;
+  --transition-logo: 0.3s;
+  --font-family-sans: Noto Sans, Fira Sans, system-ui, sans-serif;
+  --font-family-mono: JetBrains Mono, SF Mono, Monaco, Inconsolata, monospace;
+  --font-family-display: var(--font-family-display-editorial);
+  --font-family-display-editorial: Josefin Sans, system-ui, sans-serif;
+  --font-family-display-documentation: Noto Sans, system-ui, sans-serif;
+  --font-family-brand: Futura, system-ui, sans-serif;
+  --font-family-math: Noto Sans Math, Noto Sans, system-ui, sans-serif;
+  --font-size-micro: 0.75rem;
+  --font-size-small: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-readable: 1.125rem;
+  --font-size-emphasis: 1.25rem;
+  --font-size-heading-small: 1.5rem;
+  --font-size-heading-medium: 1.875rem;
+  --font-size-heading-large: 2.25rem;
+  --font-size-heading-xl: 3rem;
+  --font-weight-extralight: 200;
+  --font-weight-light: 300;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --font-weight-heading-h1: var(--font-weight-medium);
+  --font-weight-heading-h2: var(--font-weight-medium);
+  --font-weight-heading-h3: var(--font-weight-normal);
+  --font-weight-heading-h4: var(--font-weight-light);
+  --font-weight-heading-h5: var(--font-weight-light);
+  --font-weight-heading-h6: var(--font-weight-light);
+  --font-weight-heading-subtitle: var(--font-weight-semibold);
+  --font-style-normal: normal;
+  --font-style-italic: italic;
+  --font-style-oblique: oblique;
+  --font-lineHeight-tight: 1.25;
+  --font-lineHeight-normal: 1.5;
+  --font-lineHeight-relaxed: 1.625;
+  --font-feature-settings-display: "lnum";
+  --font-feature-settings-body: "normal";
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+  --spacing-xl: 2rem;
+  --spacing-2xl: 3rem;
+  --spacing-3xl: 4rem;
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --radius-full: 9999px;
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+  --color-dataviz-okabe-ito-orange: #E69F00;
+  --color-dataviz-okabe-ito-sky-blue: #56B4E9;
+  --color-dataviz-okabe-ito-bluish-green: #009E73;
+  --color-dataviz-okabe-ito-yellow: #F0E442;
+  --color-dataviz-okabe-ito-blue: #0072B2;
+  --color-dataviz-okabe-ito-vermillion: #D55E00;
+  --color-dataviz-okabe-ito-reddish-purple: #CC79A7;
+  --color-dataviz-categorical-1: #E69F00;
+  --color-dataviz-categorical-2: #56B4E9;
+  --color-dataviz-categorical-3: #009E73;
+  --color-dataviz-categorical-4: #F0E442;
+  --color-dataviz-categorical-5: #0072B2;
+  --color-dataviz-categorical-6: #D55E00;
+  --color-dataviz-categorical-7: #CC79A7;
+}
+
+:root, [data-bs-theme="light"] {
+  --color-surface-page: #ededeb;
+  --color-surface-page: color(display-p3 0.9294 0.9294 0.9223);
+  --color-surface-page-scrolled: #ededeb;
+  --color-surface-page-scrolled: color(display-p3 0.9294 0.9294 0.9223);
+  --color-surface-elevated: #f7f7f6;
+  --color-surface-elevated: color(display-p3 0.9686 0.9686 0.9651);
+  --color-surface-sunken: #faf2e3;
+  --color-surface-sunken: color(display-p3 0.9749 0.9501 0.8963);
+  --color-surface-navbar: #ededeb;
+  --color-surface-navbar: color(display-p3 0.9294 0.9294 0.9223);
+  --color-surface-navbar-scrolled: #ededeb;
+  --color-surface-navbar-scrolled: color(display-p3 0.9294 0.9294 0.9223);
+  --color-surface-code: #faf2e3;
+  --color-surface-code: color(display-p3 0.9749 0.9501 0.8963);
+  --color-border-subtle: rgba(12, 10, 9, 0.45);
+  --color-border-subtle: color(display-p3 0.0457 0.0395 0.0358 / 0.45);
+  --color-border-moderate: rgba(12, 10, 9, 0.60);
+  --color-border-moderate: color(display-p3 0.0457 0.0395 0.0358 / 0.60);
+  --color-border-strong: rgba(12, 10, 9, 0.75);
+  --color-border-strong: color(display-p3 0.0457 0.0395 0.0358 / 0.75);
+  --color-border-card: rgba(12, 10, 9, 0.60);
+  --color-border-card: color(display-p3 0.0457 0.0395 0.0358 / 0.60);
+  --color-border-code: #d6d3d1;
+  --color-border-code: color(display-p3 0.8371 0.8278 0.8205);
+  --color-content-primary: #14140f;
+  --color-content-primary: color(display-p3 0.0784 0.0784 0.0608);
+  --color-content-secondary: #6a6a6a;
+  --color-content-secondary: color(display-p3 0.4157 0.4157 0.4157);
+  --color-content-muted: #706964;
+  --color-content-muted: color(display-p3 0.4345 0.4127 0.3945);
+  --color-content-inverse: #fdf9f2;
+  --color-content-inverse: color(display-p3 0.9894 0.977 0.9518);
+  --color-interactive-primary: #434739;
+  --color-interactive-primary: color(display-p3 0.2656 0.2779 0.2287);
+  --color-interactive-hover: #363a2e;
+  --color-interactive-hover: color(display-p3 0.2146 0.2269 0.1848);
+  --color-interactive-accent: #1f618d;
+  --color-interactive-accent: color(display-p3 0.198 0.375 0.5385);
+  --color-interactive-focus: #434739;
+  --color-interactive-focus: color(display-p3 0.2656 0.2779 0.2287);
+  --color-presentation-accent: #3498db;
+  --color-presentation-accent: color(display-p3 0.3208 0.588 0.8369);
+  --color-presentation-accent-hover: #2980b9;
+  --color-presentation-accent-hover: color(display-p3 0.2638 0.495 0.7068);
+  --color-vertical-accent-dissertation: #b87333;
+  --color-vertical-accent-dissertation: color(display-p3 0.7242 0.4389 0.1259);
+  --color-vertical-accent-rpkg: #3b82f6;
+  --color-vertical-accent-rpkg: color(display-p3 0.3047 0.5035 0.9338);
+  --color-vertical-accent-SGPc: #5a6310;
+  --color-vertical-accent-SGPc: color(display-p3 0.3595 0.3871 0.1309);
+  --color-brand-mark-red: #cc0000;
+  --color-brand-mark-red: color(display-p3 0.7331 0.1519 0.1019);
+  --contrast-high: rgb(20, 20, 16);
+  --contrast-readable: rgb(20, 20, 16);
+  --contrast-medium: #7c7c7c;
+  --contrast-subtle: #7c7c7c;
+  --shadow-subtle: 0 1px 2px 0 rgb(20 20 16 / 0.05);
+  --shadow-moderate: 0 4px 6px -1px rgb(20 20 16 / 0.1);
+  --shadow-prominent: 0 10px 15px -3px rgb(20 20 16 / 0.1);
+  --border-subtle: rgba(20, 20, 16, 0.47);
+  --border-moderate: rgba(20, 20, 16, 0.63);
+  --border-focus: #3498DB;
+  --navigation-hover-background: rgba(20, 20, 16, 0.05);
+  --navigation-active-background: rgba(20, 20, 16, 0.1);
+  --color-dataviz-okabe-ito-black: #000000;
+  --color-dataviz-categorical-8: #000000;
+  --color-dataviz-uncertainty-outer: #D6D6D6;
+  --color-dataviz-uncertainty-union: #9E9E9E;
+  --color-dataviz-uncertainty-inner: #333333;
+}
+
+// ── Quarto chrome → tokens ──────────────────────────────────────────────
+body {
+  background-color: var(--color-surface-page);
+  color: var(--color-content-primary);
+}
+
+h1, h2, h3, h4, h5, h6, .title {
+  color: var(--color-content-primary);
+}
+
+// Links in running text are underlined: interactive.primary is about 1.9:1
+// against body text in light mode, so colour cannot be the only cue (WCAG 1.4.1).
+main.content :is(p, li, dd, td, blockquote, figcaption, .callout-body) a {
+  color: var(--color-interactive-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+main.content :is(p, li, dd, td, blockquote, figcaption, .callout-body) a:hover {
+  color: var(--color-interactive-hover);
+}
+
+// Navigation and the outline stay plain.
+#TOC a, nav a, .sidebar a, .navbar a, a.footnote-ref, a.anchorjs-link {
+  text-decoration: none;
+}
+
+:not(pre) > code {
+  color: var(--color-interactive-accent);
+  background-color: var(--color-surface-code);
+}
+
+pre, div.sourceCode {
+  background-color: var(--color-surface-code);
+  border: 1px solid var(--color-border-code);
+}
+
+// Quarto themes its popups as [data-theme~="quarto"] at compile time ($body-bg);
+// match that specificity so the runtime token wins.
+.tippy-box, .tippy-box[data-theme~="quarto"] {
+  background-color: var(--color-surface-elevated);
+  color: var(--color-content-primary);
+  border: 1px solid var(--color-border-subtle);
+}
+
+.tippy-box[data-theme~="quarto"] > .tippy-backdrop {
+  background-color: var(--color-surface-elevated);
+}
+
+.callout {
+  background-color: var(--color-surface-elevated);
+  border-color: var(--color-border-subtle);
+}
+
+.column-margin, .margin-aside, figcaption {
+  color: var(--color-content-secondary);
+}
+
+// Elevated cards carry an edge: in dark mode surface.elevated is about 1.06:1
+// against surface.page, so a card without one disappears.
+.di-elevated, div.abstract {
+  background-color: var(--color-surface-elevated);
+  border: 1px solid var(--color-border-subtle);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-md);
+}
+
+// ===== THEME TOGGLE STYLING =====
+// Light theme - show moon icon (switch to dark)
+
+.quarto-color-scheme-toggle .bi::before {
+  display: inline-block !important;
+  height: 1rem !important;
+  width: 1rem !important;
+  content: "" !important;
+  vertical-align: -0.125em !important;
+  background-repeat: no-repeat !important;
+  background-size: 1rem 1rem !important;
+  background-color: transparent !important;
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="%2383838F" class="bi bi-moon" viewBox="0 0 16 16"><path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278z"/></svg>') !important;
+  transition: background-image 0.25s ease;
+}
+
+.quarto-color-scheme-toggle:hover .bi::before {
+  background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="%23000000" class="bi bi-moon" viewBox="0 0 16 16"><path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278z"/></svg>') !important;
+  transition: background-image 0.25s ease;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  html {
+    scroll-behavior: smooth;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .quarto-color-scheme-toggle .bi::before {
+    transition: none !important;
+  }
+}

package/dist/tailwind-preset.js

@@ -1,12 +1,21 @@
 // @dataimago/css Tailwind preset — Generated from @dataimago/tokens
-// Source files: packages/tokens/src/colors.json, packages/tokens/src/typography.json
+// Source files:
+//   packages/tokens/src/colors.json    (palette + functional colors)
+//   packages/tokens/src/typography.json (font family, size, weight)
+//   packages/tokens/src/spacing.json    (spacing, radius, shadow simple scales)
+//   packages/tokens/src/effects.json    (theme-aware shadow, transition)
 // Regenerated by packages/css/build.mjs on every release.
 //
-// Iteration-1 (2026-04-30) brought: stone+forest palette anchor, paper as
-// renamed cream (with deprecated cream alias preserved through 0.2.x),
-// editorial/documentation display family split, font.size scale, math family.
-// See wiki/decisions/{josefin-weight-floor,display-family-split,h1-weight-medium,
-// display-lining-figures,font-trim-deferred}.md for the governance.
+// Iteration-1 (2026-04-30): stone+forest palette anchor, paper-as-renamed-cream
+// (with deprecated cream alias through 0.2.x), editorial/documentation display
+// family split, font.size scale, math family. See wiki/decisions/{josefin-weight-floor,
+// display-family-split, h1-weight-medium, display-lining-figures, font-trim-deferred}.md.
+//
+// Stage 2.3 (2026-05-04): Tailwind preset extended to spacing/borderRadius/
+// boxShadow/transitionDuration so consumers can write `p-md`, `rounded-lg`,
+// `shadow-subtle`, `duration-quick` Tailwind classes throughout instead of
+// reaching for inline `var(--*)` references. theme.extend merges with Tailwind
+// defaults at colliding keys (e.g. `rounded-md` becomes the dataimago value).
 
 /** @type {import('tailwindcss').Config} */
 module.exports = {
@@ -71,10 +80,12 @@ module.exports = {
                       "900": "#612b16"
               },
               "accent": {
-                      "50": "#fdf2f2",
-                      "500": "#b54a27",
-                      "600": "#9a3e20",
-                      "700": "#7d321a"
+                      "50": "#f0f8fc",
+                      "300": "#3498DB",
+                      "400": "#2980B9",
+                      "500": "#1f618d",
+                      "600": "#154d6f",
+                      "700": "#0f3a52"
               },
               "presentation-blue": {
                       "50": "#f0f8fc",
@@ -148,6 +159,42 @@ module.exports = {
               "heading-medium": "1.875rem",
               "heading-large": "2.25rem",
               "heading-xl": "3rem"
+      },
+      spacing: {
+              "xs": "0.25rem",
+              "sm": "0.5rem",
+              "md": "1rem",
+              "lg": "1.5rem",
+              "xl": "2rem",
+              "2xl": "3rem",
+              "3xl": "4rem"
+      },
+      borderRadius: {
+              "sm": "0.25rem",
+              "md": "0.5rem",
+              "lg": "0.75rem",
+              "xl": "1rem",
+              "full": "9999px"
+      },
+      boxShadow: {
+              "sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
+              "md": "0 4px 6px -1px rgb(0 0 0 / 0.1)",
+              "lg": "0 10px 15px -3px rgb(0 0 0 / 0.1)",
+              "xl": "0 20px 25px -5px rgb(0 0 0 / 0.1)",
+              "subtle": "var(--shadow-subtle, 0 1px 2px 0 rgb(20 20 16 / 0.05))",
+              "moderate": "var(--shadow-moderate, 0 4px 6px -1px rgb(20 20 16 / 0.1))",
+              "prominent": "var(--shadow-prominent, 0 10px 15px -3px rgb(20 20 16 / 0.1))"
+      },
+      transitionDuration: {
+              "quick": "0.15s",
+              "standard": "0.25s",
+              "smooth": "0.35s",
+              "logo": "0.3s"
+      },
+      transitionTimingFunction: {
+              "quick": "ease",
+              "standard": "ease-in-out",
+              "smooth": "ease"
       }
     }
   }

package/dist/templates/KNOWLEDGE-explorer.md

@@ -0,0 +1,236 @@
+<!-- @dataimago/css@0.1.0-alpha.20 dist/templates/KNOWLEDGE-explorer.md · sha256:907c08638ed56813d453227759e29de08350465885d11f0efe94ec7ba8c42a50 · generated from tokens; do not edit · restore: npx -p @dataimago/css@0.1.0-alpha.20 dataimago-sync -->
+# {{PROJECT_NAME}} — Knowledge Base Operating Manual
+
+**Domain:** {{DOMAIN_NAME}}
+**Type:** explorer
+**Explorer dimension:** {{EXPLORER_DIMENSION}}
+**Generated:** {{GENERATED_DATE}}
+**Framework:** [dataimago-design]({{FRAMEWORK_WIKI_URL}}/wiki/index.md)
+
+This file is the operating manual for the **{{PROJECT_NAME}}** knowledge base — an AI-maintained wiki that documents the dimensions, attributes, datasets, and data quality considerations that make this application trustworthy and navigable. Read it at the start of every knowledge-work session.
+
+---
+
+## Role
+
+You are the wiki maintainer for **{{PROJECT_NAME}}**'s knowledge base — an `explorer`-type domain wiki organized around the `{{EXPLORER_DIMENSION}}` dimension. This application has no thesis to advance; it makes a dataset navigable. Your job is to ensure that every piece of data the application presents is accurately documented — what it means, where it came from, what its limitations are.
+
+Your job is to:
+- Document new attributes as they are added to the application
+- Summarize source datasets and their quality characteristics
+- Answer queries about data provenance, coverage, and interpretation
+- File answers as `wiki/analyses/` pages so knowledge compounds
+- Lint the wiki for gaps in attribute documentation and stale dataset information
+
+You never modify files in `raw/`. You own everything in `wiki/`.
+
+The framework layer (how this application is built) is documented in the dataimago-design wiki (see `dataimago-framework.json` for the URL). Data and content questions belong here; build and architecture questions belong there.
+
+---
+
+## Session Start Protocol
+
+At the start of every knowledge-work session:
+1. Read this file (KNOWLEDGE.md)
+2. Read `wiki/index.md` to orient to the current knowledge base state
+3. Read the last 5 entries of `wiki/log.md` to understand recent activity
+4. Check `wiki/attributes/` for any attributes flagged as needing documentation updates
+5. Read the framework wiki index (URL in `dataimago-framework.json`) for framework context (optional unless architecture is relevant)
+6. Ask the user: ingest new data, document an attribute, answer a query, or something else?
+
+---
+
+## Directory Structure
+
+```
+wiki/
+├── index.md          ← Master catalog of all wiki pages
+├── overview.md       ← High-level synthesis: what data this application holds and why
+├── glossary.md       ← Canonical terminology for this domain
+├── log.md            ← Append-only activity record
+├── dimensions/       ← The organizing axes of the explorer (geography, time, etc.)
+├── attributes/       ← Each measurable property: meaning, source, coverage, caveats
+├── datasets/         ← Data sources: provenance, update cadence, coverage gaps
+├── sources/          ← Authoritative sources for datasets and attribute definitions
+├── personas/         ← Who uses the explorer and what they discover with it
+└── analyses/         ← Patterns, comparisons, and insights surfaced from the data
+
+raw/
+├── papers/           ← Academic sources, methodology documents
+├── conversations/    ← AI dialogues, decisions, notes
+├── data/             ← Raw dataset files, exports from R
+└── references/       ← External data portals, API specs, codebooks
+```
+
+---
+
+## Entity Types
+
+| Type | Location | Page purpose |
+|---|---|---|
+| **Dimension** | `wiki/dimensions/` | The organizing axes: what they cover, how entities are identified, edge cases |
+| **Attribute** | `wiki/attributes/` | Each measurable property: precise definition, source, geographic/temporal coverage, caveats |
+| **Dataset** | `wiki/datasets/` | A data source: provenance, update cadence, coverage gaps, known issues, R dataset name |
+| **Source** | `wiki/sources/` | An authoritative reference for an attribute definition or dataset methodology |
+| **Persona** | `wiki/personas/` | A user type: what they're trying to discover, what attributes they care about |
+| **Analysis** | `wiki/analyses/` | Patterns found, comparisons made, insights derived from the data |
+
+---
+
+## The Attribute Page — Core Knowledge Atom
+
+The `wiki/attributes/` directory is the most important part of this wiki. Every attribute the application exposes must have a page that documents:
+
+```markdown
+---
+title: <attribute human name>
+type: attribute
+attribute_id: <the parameter name used in R functions and API endpoints>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+dataset: <wiki/datasets/dataset-name.md>
+sources:
+  - <authoritative source for the attribute definition>
+tags: []
+---
+
+One-line description of what this attribute measures.
+
+## Definition
+Precise definition — not just a label. What exactly is being measured? What is the unit?
+What is the reference period (for point-in-time attributes)?
+
+## Data Source
+- Dataset: [[dataset-name]] 
+- R dataset object: `{{PROJECT_NAME}}::dataset_name`
+- R retrieval function: `get_entity_profile(entity_id, attributes = "{{ATTRIBUTE_ID}}")`
+
+## Coverage
+- Entities covered: (e.g., "193 UN member states", "47 European countries")
+- Temporal coverage: (e.g., "2000–2023 annually", "2022 only")
+- Known gaps: (e.g., "Missing for small island nations with population < 50,000")
+
+## Data Quality
+- Source reliability: (official statistics / derived / estimated / self-reported)
+- Known issues: (e.g., "Pre-2010 figures use different methodology")
+- Comparability caveats: (e.g., "Purchasing power adjustments vary by source year")
+
+## Interpretation
+For non-specialist audiences: what does a high/low value on this attribute mean?
+What should users NOT conclude from this attribute?
+
+## Related Attributes
+- [[attribute-name]] — (relationship, e.g., "often inversely correlated")
+```
+
+---
+
+## Workflows
+
+### Ingest a New Dataset
+
+1. Read the raw data file from `raw/data/` and any codebook from `raw/references/`
+2. Create a `wiki/datasets/` page documenting provenance, coverage, and update cadence
+3. Create a `wiki/attributes/` page for each attribute the dataset provides
+4. Update `wiki/dimensions/` if the dataset covers new entities or extends temporal range
+5. Update `wiki/glossary.md` with any new technical terms
+6. Update `wiki/index.md` and append to `wiki/log.md`
+
+### Document a New Attribute
+
+1. Identify the authoritative source for the attribute's definition
+2. Create a `wiki/attributes/` page following the template above
+3. Verify the R retrieval function returns correct data for the attribute
+4. Add the attribute to the relevant `wiki/datasets/` page
+5. Update `wiki/index.md` and append to `wiki/log.md`
+
+### Ingest a Paper or Reference
+
+1. Read from `raw/papers/`
+2. Determine: does this define an attribute? challenge a dataset's methodology? describe a dimension?
+3. Create a `wiki/sources/` page summarizing the key claims
+4. Link to the affected `wiki/attributes/` or `wiki/datasets/` pages
+5. Update `wiki/glossary.md` and append to `wiki/log.md`
+
+### Query
+
+1. Read `wiki/index.md` to identify relevant pages (typically `wiki/attributes/` and `wiki/datasets/`)
+2. Read those pages
+3. Synthesize a clear answer with citations
+4. Ask: "Should I file this as an analysis?" If yes, save to `wiki/analyses/`
+5. Append to `wiki/log.md`
+
+### Lint
+
+1. Check every attribute in `wiki/attributes/` has: definition, coverage, data quality, interpretation
+2. Check every dataset in `wiki/datasets/` has: provenance, update cadence, known gaps
+3. Check for attributes used in the application but not documented in the wiki
+4. Check for stale dataset entries (coverage dates that should have been updated)
+5. Report findings and propose fixes
+6. Append to `wiki/log.md`
+
+---
+
+## Log Format
+
+```
+## [YYYY-MM-DD] <action> | <title>
+
+**Action:** <description>
+Pages created: ...
+Pages updated: ...
+Key additions: ...
+```
+
+---
+
+## Terminology Discipline
+
+- Check `wiki/glossary.md` before using any domain term
+- Attribute IDs (used in R functions and API endpoints) must be consistent: `{{ATTRIBUTE_ID}}` form
+- Entity identifiers must be consistent: `{{EXPLORER_DIMENSION}}` → [describe ID format, e.g., ISO 3166-1 alpha-3 for countries]
+- Key terms for this domain: [populated by domain expert — add canonical terms here as the wiki develops]
+
+---
+
+## R Functions in This Application
+
+The following R functions are the retrieval backbone of {{PROJECT_NAME}}:
+
+{{EXPORTED_FUNCTIONS}}
+
+**Standard explorer function pattern:**
+- Every attribute is retrievable via `get_entity_profile(entity_id, attributes = "attribute_id")`
+- Every attribute is comparable via `compare_entities(entity_ids, "attribute_id")`
+- Discovery: `get_attributes()` returns all attributes with their wiki descriptions
+- Discovery: `get_entities()` returns all entities with their available attributes
+
+---
+
+## Data Quality Standards
+
+This application makes claims about the world. Every attribute must meet these standards before it can be displayed to users:
+
+1. **Defined** — A `wiki/attributes/` page exists with a precise definition
+2. **Sourced** — The data source is documented in a `wiki/datasets/` page
+3. **Bounded** — Coverage (entities and time period) is documented
+4. **Caveated** — Known quality issues and comparability limits are documented
+5. **Interpreted** — A plain-language interpretation is available for non-specialist users
+
+Attributes that fail any of these standards should be marked `status: draft` in their frontmatter and excluded from the production data explorer until the standard is met.
+
+---
+
+## Connection to the Framework Layer
+
+This wiki documents **what data** this application holds and **what it means**. The dataimago-design wiki documents **how** the application is built. The connection:
+
+```
+wiki/attributes/greeting.md
+  → documents HelloWorld::Hello_World dataset
+    → retrieved via get_entity_profile(entity_id)
+      → exposed at GET /entity/{id}?attributes=greeting
+        → documented in dataimago-design/wiki/patterns/rest-api-from-r.md
+```
+
+Do not duplicate framework documentation here. Reference it.