@glw907/cairn-cms 0.7.0 → 0.9.0

package/src/lib/components/ConceptList.svelte

@@ -17,9 +17,14 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   let title = $state('');
   let slug = $state('');
   let slugEdited = $state(false);
+  // Default the date client-side so the SSR pass and hydration agree across UTC midnight.
+  let dateDefault = $state('');
+  $effect(() => {
+    dateDefault = new Date().toISOString().slice(0, 10);
+  });
 
   const derivedSlug = $derived(slugEdited ? slug : slugify(title));
-  const slugPlaceholder = $derived(data.dated ? '2026-05-my-entry' : 'about-us');
+  const slugPlaceholder = $derived(data.dated ? 'my-entry' : 'about-us');
 </script>
 
 <header class="mb-4 flex items-center justify-between">
@@ -58,14 +63,13 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   <h2 class="text-sm font-semibold">New entry</h2>
   <label class="flex flex-col gap-1">
     <span class="text-sm font-medium">Title</span>
-    <input class="input" name="title" aria-label="Title" bind:value={title} required />
+    <input class="input" name="title" bind:value={title} required />
   </label>
   <label class="flex flex-col gap-1">
     <span class="text-sm font-medium">Slug</span>
     <input
       class="input"
       name="slug"
-      aria-label="Slug"
       placeholder={slugPlaceholder}
       value={derivedSlug}
       oninput={(e) => { slugEdited = true; slug = e.currentTarget.value; }}
@@ -74,7 +78,7 @@ plus a new-entry form. The slug auto-derives from the title until the author edi
   {#if data.dated}
     <label class="flex flex-col gap-1">
       <span class="text-sm font-medium">Date</span>
-      <input class="input" type="date" name="date" aria-label="Date" />
+      <input class="input" type="date" name="date" value={dateDefault} />
     </label>
   {/if}
   <button type="submit" class="btn btn-primary self-start">Create</button>

package/src/lib/components/EditPage.svelte

@@ -1,6 +1,6 @@
 <!--
 @component
-The differentiated editor: the per-concept frontmatter form (from `data.fields`) beside the Carta
+The differentiated editor: the per-concept frontmatter form (from `data.fields`) beside the
 markdown editor and a live, design-accurate preview. The whole surface is one form posting to the
 `?/save` action; the preview toggle persists per user in localStorage (spec §7.6).
 -->
@@ -18,13 +18,11 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
     data: EditData & { siteName: string };
     /** The site's component registry, for the insert palette. */
     registry?: ComponentRegistry;
-    /** Carta preview plugins from the adapter, for the design-accurate preview. */
-    preview?: unknown[];
     /** The site's design-accurate render pipeline; the preview pane sanitizes its output. */
     render?: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
   }
 
-  let { data, registry, preview = [], render }: Props = $props();
+  let { data, registry, render }: Props = $props();
 
   // `body` is local editor state seeded once from the prop; it diverges as the user types.
   // untrack() captures the initial value without subscribing to future prop changes.
@@ -46,7 +44,7 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   }
 
   // Render the design-accurate preview as the body changes, debounced, and sanitize before the DOM.
-  // The sanitize is the one barrier between editor-authored markdown and the page (Carta is unsanitized).
+  // The sanitize is the one barrier between editor-authored markdown and the page (the editor is unsanitized).
   // previewRun is a plain counter (not reactive state) used as a latest-wins guard: if a slow earlier
   // async render call resolves after a newer one has started, the stale result is discarded.
   let previewRun = 0;
@@ -103,7 +101,7 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
 
   <div class="lg:order-1">
     <div class="rounded-box border border-base-300 bg-base-100 overflow-hidden">
-      <MarkdownEditor bind:value={body} name="body" plugins={preview} registerInsert={(fn) => (insert = fn)} />
+      <MarkdownEditor bind:value={body} name="body" registerInsert={(fn) => (insert = fn)} />
     </div>
     {#if showPreview}
       <section

package/src/lib/components/EditorToolbar.svelte

@@ -0,0 +1,61 @@
+<!--
+@component
+The editor's formatting toolbar: bold, italic, heading, link, bulleted list, quote, code. Each button
+asks the host to apply a markdown transform to the current selection. Carta supplied this row before;
+cairn owns it now so the edit surface stays swappable. The glyphs are stroke SVG icons in the admin's
+house style (24x24 viewBox, `currentColor`, round caps), so the row matches the rest of the surface.
+-->
+<script lang="ts">
+  import type { FormatKind } from './markdown-format.js';
+
+  interface Props {
+    /** Apply a markdown transform to the editor's current selection. */
+    format: (kind: FormatKind) => void;
+  }
+
+  let { format }: Props = $props();
+
+  // Each icon is a set of stroke `<path>` d-strings rendered into the shared 24x24 svg below, so the
+  // markup stays declarative (no per-icon raw html). Paths follow the house outline style.
+  const buttons: { kind: FormatKind; label: string; paths: string[] }[] = [
+    { kind: 'bold', label: 'Bold', paths: ['M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8'] },
+    { kind: 'italic', label: 'Italic', paths: ['M19 4h-9', 'M14 20H5', 'M15 4 9 20'] },
+    { kind: 'heading', label: 'Heading', paths: ['M6 4v16', 'M18 4v16', 'M6 12h12'] },
+    {
+      kind: 'link',
+      label: 'Link',
+      paths: [
+        'M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71',
+        'M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71',
+      ],
+    },
+    { kind: 'ul', label: 'Bulleted list', paths: ['M8 6h13', 'M8 12h13', 'M8 18h13', 'M3 6h.01', 'M3 12h.01', 'M3 18h.01'] },
+    {
+      kind: 'quote',
+      label: 'Quote',
+      paths: [
+        'M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1 1 1 0 0 0 1 1 4 4 0 0 0 4-4V5a2 2 0 0 0-2-2z',
+        'M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1 1 1 0 0 0 1 1 4 4 0 0 0 4-4V5a2 2 0 0 0-2-2z',
+      ],
+    },
+    { kind: 'code', label: 'Code', paths: ['M16 18l6-6-6-6', 'M8 6l-6 6 6 6'] },
+  ];
+</script>
+
+<div class="border-base-300 bg-base-200 flex gap-1 border-b p-1" role="toolbar" aria-label="Formatting">
+  {#each buttons as button (button.kind)}
+    <button
+      type="button"
+      class="btn btn-ghost btn-sm btn-square"
+      aria-label={button.label}
+      title={button.label}
+      onclick={() => format(button.kind)}
+    >
+      <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
+        {#each button.paths as d (d)}
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d={d} />
+        {/each}
+      </svg>
+    </button>
+  {/each}
+</div>

package/src/lib/components/MarkdownEditor.svelte

@@ -1,81 +1,120 @@
 <!--
 @component
-The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over Carta exposing a bindable value
-and a cursor-insert callback. Carta and Shiki are client-only, so the editor mounts after the
-component does; until then the hidden field still carries the value so the form submits correctly.
-Swapping Carta for a bare CodeMirror editor stays a one-file change.
+The `MarkdownEditor` seam (spec §6, seam 5): a thin wrapper over CodeMirror 6 exposing a bindable
+value and a cursor-insert callback. CodeMirror is client-only, so it mounts after the component does
+through a dynamic import; until then a plain textarea carries the value so the form still submits, and
+the hidden field mirrors the value throughout. The edit surface owns its toolbar; the design-accurate
+preview lives in EditPage through the adapter's render. Swapping the editor stays a one-file change.
 -->
 <script lang="ts">
-  import { onMount } from 'svelte';
+  import { onMount, onDestroy } from 'svelte';
+  import EditorToolbar from './EditorToolbar.svelte';
+  import { applyMarkdownFormat, type FormatKind } from './markdown-format.js';
 
   interface Props {
     /** The markdown source; bindable so the parent reads edits back. */
     value: string;
     /** The hidden field name the value is mirrored to for form submit. */
     name: string;
-    /** Carta extensions from the adapter, for the design-accurate preview. */
-    plugins?: unknown[];
     /** Receives a `(text) => void` that inserts at the cursor; the palette calls it. */
     registerInsert?: (insert: (text: string) => void) => void;
   }
 
-  let { value = $bindable(), name, plugins = [], registerInsert }: Props = $props();
-
-  // Local structural type for the Carta editing surface this seam uses. carta-md re-exports its
-  // Svelte components from the package entry, so its `Carta` class is not reachable as a named
-  // export under NodeNext; a structural type stays compatible without naming it (the shape
-  // legacy/src/lib/editor.ts relied on, verified against carta-md@4.11).
-  interface CartaInput {
-    getSelection(): { start: number };
-    insertAt(position: number, text: string): void;
-    update(): boolean;
-  }
-  interface CartaLike {
-    input?: CartaInput;
-  }
+  let { value = $bindable(), name, registerInsert }: Props = $props();
 
+  let host = $state<HTMLDivElement | null>(null);
   let mounted = $state(false);
-  // Carta and the MarkdownEditor component load only in the browser, after mount, so the server
-  // bundle never pulls in Carta or Shiki (guarded by the carta-boundary test). The component keeps
-  // its real type, so `value` stays bindable; the Carta constructor is reached through a cast
-  // because the package entry does not surface the class by name.
-  let Editor = $state<(typeof import('carta-md'))['MarkdownEditor'] | null>(null);
-  let carta = $state<CartaLike | null>(null);
+  // The CodeMirror view, untyped at the runtime boundary because @codemirror/* loads only in the
+  // browser. The type-only `import(...)` annotation is erased; the value import is dynamic in onMount,
+  // so the server bundle never pulls CodeMirror (guarded by the editor-boundary test).
+  let view: import('@codemirror/view').EditorView | null = null;
 
   onMount(async () => {
-    const mod = await import('carta-md');
-    const CartaCtor = (
-      mod as unknown as { Carta: new (options: { extensions?: unknown[]; sanitizer: false }) => CartaLike }
-    ).Carta;
-    const instance = new CartaCtor({
-      extensions: plugins,
-      // Sanitization is the site adapter's concern; the seam passes raw markdown through.
-      sanitizer: false,
-    });
-    carta = instance;
-    Editor = mod.MarkdownEditor;
-    // Insert at the current cursor through carta.input once the editor is mounted; fall back to
-    // appending while input is not yet populated (the pre-mount textarea phase).
-    registerInsert?.((text: string) => {
-      const inp = instance.input;
-      if (inp) {
-        const pos = inp.getSelection().start;
-        const prefix = pos > 0 ? '\n\n' : '';
-        inp.insertAt(pos, `${prefix}${text}`);
-        inp.update();
-      } else {
-        value = value ? `${value}\n\n${text}` : text;
-      }
+    const viewMod = await import('@codemirror/view');
+    const stateMod = await import('@codemirror/state');
+    const markdownMod = await import('@codemirror/lang-markdown');
+    const commandsMod = await import('@codemirror/commands');
+    const languageMod = await import('@codemirror/language');
+
+    if (!host) return;
+
+    const { EditorView, keymap } = viewMod;
+    const theme = EditorView.theme(
+      {
+        '&': { backgroundColor: 'var(--color-base-100)', color: 'var(--color-base-content)', fontSize: '0.875rem' },
+        '.cm-content': { fontFamily: 'ui-monospace, monospace', padding: '0.75rem', lineHeight: '1.7' },
+        '.cm-cursor': { borderLeftColor: 'var(--color-primary)' },
+        '&.cm-focused': { outline: '2px solid var(--color-primary)', outlineOffset: '-2px' },
+        '.cm-line': { padding: '0' },
+      },
+      { dark: false },
+    );
+
+    view = new EditorView({
+      parent: host,
+      state: stateMod.EditorState.create({
+        doc: value,
+        extensions: [
+          commandsMod.history(),
+          keymap.of([...commandsMod.defaultKeymap, ...commandsMod.historyKeymap]),
+          markdownMod.markdown(),
+          EditorView.lineWrapping,
+          languageMod.syntaxHighlighting(languageMod.defaultHighlightStyle, { fallback: true }),
+          theme,
+          EditorView.updateListener.of((update) => {
+            if (update.docChanged) value = update.state.doc.toString();
+          }),
+        ],
+      }),
     });
+
+    registerInsert?.(insertAtCursor);
     mounted = true;
   });
+
+  onDestroy(() => view?.destroy());
+
+  // Reconcile an externally reassigned `value` into the mounted editor. A no-op until `view` exists,
+  // and the doc-equality guard ignores the updateListener's own writes so the two never feed back.
+  $effect(() => {
+    const incoming = value;
+    if (!view) return;
+    const current = view.state.doc.toString();
+    if (incoming === current) return;
+    view.dispatch({ changes: { from: 0, to: current.length, insert: incoming } });
+  });
+
+  function insertAtCursor(text: string) {
+    if (!view) {
+      value = value ? `${value}\n\n${text}` : text;
+      return;
+    }
+    const pos = view.state.selection.main.head;
+    const prefix = pos > 0 ? '\n\n' : '';
+    const insert = `${prefix}${text}`;
+    view.dispatch({ changes: { from: pos, insert }, selection: { anchor: pos + insert.length } });
+    view.focus();
+  }
+
+  function applyFormat(kind: FormatKind) {
+    if (!view) return;
+    const { from, to } = view.state.selection.main;
+    const doc = view.state.doc.toString();
+    const next = applyMarkdownFormat(doc, from, to, kind);
+    view.dispatch({
+      changes: { from: 0, to: doc.length, insert: next.doc },
+      selection: { anchor: next.from, head: next.to },
+    });
+    view.focus();
+  }
 </script>
 
-<input type="hidden" {name} value={value} />
+<input type="hidden" {name} {value} />
 
-{#if mounted && Editor && carta}
-  {@const EditorComponent = Editor}
-  <EditorComponent carta={carta as never} bind:value theme="default" mode="tabs" />
-{:else}
-  <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
-{/if}
+<div class="border-base-300 overflow-hidden rounded-box border">
+  <EditorToolbar format={applyFormat} />
+  <div bind:this={host}></div>
+  {#if !mounted}
+    <textarea class="textarea min-h-64 w-full font-mono text-sm" bind:value aria-label="Markdown source"></textarea>
+  {/if}
+</div>

package/src/lib/components/markdown-format.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure markdown selection transforms for the editor toolbar. Each call maps a document and a
+ * selection range to a new document and a new selection, with no DOM. The MarkdownEditor view
+ * dispatches the result; keeping the logic here lets it unit-test without a browser.
+ */
+export type FormatKind = 'bold' | 'italic' | 'code' | 'heading' | 'quote' | 'ul' | 'link';
+
+export interface FormatResult {
+  doc: string;
+  from: number;
+  to: number;
+}
+
+const WRAP: Record<'bold' | 'italic' | 'code', string> = { bold: '**', italic: '_', code: '`' };
+const LINE_PREFIX: Record<'heading' | 'quote' | 'ul', string> = { heading: '# ', quote: '> ', ul: '- ' };
+
+export function applyMarkdownFormat(doc: string, from: number, to: number, kind: FormatKind): FormatResult {
+  if (kind === 'bold' || kind === 'italic' || kind === 'code') {
+    const marker = WRAP[kind];
+    const next = doc.slice(0, from) + marker + doc.slice(from, to) + marker + doc.slice(to);
+    return { doc: next, from: from + marker.length, to: to + marker.length };
+  }
+
+  if (kind === 'link') {
+    const text = doc.slice(from, to);
+    const placeholder = 'url';
+    const lead = `[${text}](`; // everything before the url placeholder
+    const inserted = `${lead}${placeholder})`;
+    const urlStart = from + lead.length;
+    return { doc: doc.slice(0, from) + inserted + doc.slice(to), from: urlStart, to: urlStart + placeholder.length };
+  }
+
+  const prefix = LINE_PREFIX[kind];
+  const lineStart = doc.lastIndexOf('\n', from - 1) + 1; // 0 when the selection is on the first line
+  const region = doc.slice(lineStart, to);
+  const prefixed = region.replace(/^/gm, prefix);
+  const added = prefixed.length - region.length;
+  return { doc: doc.slice(0, lineStart) + prefixed + doc.slice(to), from: from + prefix.length, to: to + added };
+}

package/src/lib/content/compose.ts

@@ -3,7 +3,7 @@
 // the same way and contributes the same kinds of things: nav entries, route logic,
 // concepts, components, field types, and save hooks. Shaped now so the extension contract
 // is additive later.
-import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, FieldTypeDef } from './types.js';
+import type { AdminPanel, CairnAdapter, CairnExtension, CairnRuntime, ConceptConfig, ConceptUrlPolicy, FieldTypeDef } from './types.js';
 import { normalizeConcepts } from './concepts.js';
 
 /**
@@ -13,6 +13,7 @@ import { normalizeConcepts } from './concepts.js';
 export function composeRuntime(
   adapter: CairnAdapter,
   extensions: CairnExtension[] = [],
+  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
 ): CairnRuntime {
   const content: Record<string, ConceptConfig | undefined> = { ...adapter.content };
   const adminPanels: AdminPanel[] = [];
@@ -26,7 +27,7 @@ export function composeRuntime(
   }
   return {
     siteName: adapter.siteName,
-    concepts: normalizeConcepts(content),
+    concepts: normalizeConcepts(content, urlPolicy),
     backend: adapter.backend,
     sender: adapter.sender,
     render: adapter.render,

package/src/lib/content/concepts.ts

@@ -3,7 +3,7 @@
 // (id, label, directory, concept-fixed routing, fields, validator) the admin reads. A
 // future Fragments concept attaches by adding one key under `content` and one routing
 // entry, with no reshape here.
-import type { ConceptConfig, ConceptDescriptor, RoutingRule } from './types.js';
+import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
 
 /**
  * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
@@ -29,24 +29,28 @@ function defaultPermalink(id: string): string {
 }
 
 /**
- * Normalize an adapter's declared concepts into uniform descriptors (seam 1). Each declared
- * key under `content` becomes one descriptor; an undeclared (`undefined`) concept is
- * skipped. `routing` is injectable so a contract test can prove a new concept attaches
- * additively; production passes the default `CONCEPT_ROUTING`.
+ * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
+ * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
+ * concept id; each value defaults when the YAML omits it (`/:slug` for Pages, `/<id>/:slug`
+ * otherwise; `datePrefix` defaults to `day`). `routing` is injectable so a contract test can prove
+ * a new concept attaches additively; production passes the default `CONCEPT_ROUTING`.
  */
 export function normalizeConcepts(
   content: Record<string, ConceptConfig | undefined>,
+  urlPolicy: Record<string, ConceptUrlPolicy | undefined> = {},
   routing: Readonly<Record<string, RoutingRule>> = CONCEPT_ROUTING,
 ): ConceptDescriptor[] {
   const descriptors: ConceptDescriptor[] = [];
   for (const [id, config] of Object.entries(content)) {
     if (!config) continue;
+    const policy = urlPolicy[id] ?? {};
     descriptors.push({
       id,
       label: config.label ?? defaultLabel(id),
       dir: config.dir,
       routing: routing[id] ?? DEFAULT_ROUTING,
-      permalink: config.permalink ?? defaultPermalink(id),
+      permalink: policy.permalink ?? defaultPermalink(id),
+      datePrefix: policy.datePrefix ?? 'day',
       fields: config.fields,
       validate: config.validate,
     });

package/src/lib/content/ids.ts

@@ -36,3 +36,47 @@ export function slugify(title: string): string {
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '');
 }
+
+/** Filename date-prefix granularity for a dated concept: the leading `YYYY[-MM[-DD]]-` on the stem. */
+export type DatePrefix = 'year' | 'month' | 'day';
+
+/** The leading date-prefix shape for each granularity. */
+const DATE_PREFIX_RE: Record<DatePrefix, RegExp> = {
+  year: /^\d{4}-/,
+  month: /^\d{4}-\d{2}-/,
+  day: /^\d{4}-\d{2}-\d{2}-/,
+};
+
+/**
+ * The URL slug for an id. A dated concept passes its `datePrefix` and the leading date prefix is
+ * stripped when present; a non-dated concept passes `null` and the id is returned verbatim. Only
+ * the leading prefix is removed, so a year-like tail (a post titled "2024 Recap") stays in the slug.
+ */
+export function slugFromId(id: string, datePrefix: DatePrefix | null): string {
+  if (!datePrefix) return id;
+  return id.replace(DATE_PREFIX_RE[datePrefix], '');
+}
+
+/**
+ * Compose a dated entry's id from a `YYYY-MM-DD` date, a date-free slug, and the concept's
+ * granularity: the date truncated to the granularity, a hyphen, then the slug. Throws on a
+ * malformed date so a bad create fails before touching git.
+ */
+export function composeDatedId(date: string, slug: string, datePrefix: DatePrefix): string {
+  const m = date.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m) throw new Error(`composeDatedId: malformed date "${date}"`);
+  const [, year, month, day] = m;
+  let prefix: string;
+  switch (datePrefix) {
+    case 'year':
+      prefix = year;
+      break;
+    case 'month':
+      prefix = `${year}-${month}`;
+      break;
+    case 'day':
+      prefix = `${year}-${month}-${day}`;
+      break;
+  }
+  return `${prefix}-${slug}`;
+}

package/src/lib/content/permalink.ts

@@ -20,10 +20,10 @@ function dateParts(date?: string): { year: string; month: string; day: string }
  */
 export function permalink(
   descriptor: ConceptDescriptor,
-  entry: { id: string; date?: string },
+  entry: { id: string; slug: string; date?: string },
 ): string {
   return descriptor.permalink.replace(/:(\w+)/g, (_match, token: string) => {
-    if (token === 'slug') return entry.id;
+    if (token === 'slug') return entry.slug;
     if (token === 'year' || token === 'month' || token === 'day') {
       const parts = dateParts(entry.date);
       if (!parts) {

package/src/lib/content/types.ts

@@ -8,6 +8,7 @@
 // descriptors are plain data so a `load` function can hand them across the server-to-client
 // boundary to the editor form.
 import type { ComponentRegistry } from '../render/registry.js';
+import type { DatePrefix } from './ids.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -84,13 +85,17 @@ export interface ConceptConfig {
   fields: FrontmatterField[];
   /** Validate submitted frontmatter before any commit. */
   validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
-  /**
-   * Public URL pattern for this concept, a `/`-prefixed string of literal segments and the
-   * tokens `:slug`, `:year`, `:month`, `:day`. `normalizeConcepts` fills a per-concept
-   * default when omitted (`/:slug` for Pages, `/<conceptId>/:slug` otherwise). The pattern
-   * must agree with the site's filesystem route directory.
-   */
+}
+
+/**
+ * A concept's URL policy, set per concept in the YAML site-config (not the adapter). `permalink` is
+ * a `/`-prefixed pattern of literal segments and the tokens `:slug`, `:year`, `:month`, `:day`.
+ * `datePrefix` is the filename date-prefix granularity for a dated concept. Both default in
+ * `normalizeConcepts` when omitted.
+ */
+export interface ConceptUrlPolicy {
   permalink?: string;
+  datePrefix?: DatePrefix;
 }
 
 /** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
@@ -175,6 +180,8 @@ export interface ConceptDescriptor {
   routing: RoutingRule;
   /** The resolved permalink pattern, defaulted by `normalizeConcepts`. */
   permalink: string;
+  /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
+  datePrefix: DatePrefix;
   fields: FrontmatterField[];
   validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
 }

package/src/lib/delivery/content-index.ts

@@ -3,7 +3,7 @@
 // returns cheap plain-data summaries plus an on-demand detail lookup. It is concept-generic:
 // every operation reads the descriptor and its routing rule, never a hardcoded concept id.
 import { parseMarkdown } from '../content/frontmatter.js';
-import { idFromFilename } from '../content/ids.js';
+import { idFromFilename, slugFromId } from '../content/ids.js';
 import { permalink } from '../content/permalink.js';
 import { deriveExcerpt, wordCount } from './excerpt.js';
 import type { ConceptDescriptor } from '../content/types.js';
@@ -17,6 +17,7 @@ export interface RawFile {
 /** The cheap, plain-data view of one entry, for lists, feeds, and the sitemap. */
 export interface ContentSummary {
   id: string;
+  slug: string;
   permalink: string;
   title: string;
   date?: string;
@@ -70,11 +71,13 @@ function asTags(value: unknown): string[] {
 export function createContentIndex(files: RawFile[], descriptor: ConceptDescriptor): ContentIndex {
   const entries: ContentEntry[] = files.map((file) => {
     const id = idFromFilename(basename(file.path));
+    const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
     const { frontmatter, body } = parseMarkdown(file.raw);
     const date = asDate(frontmatter.date);
     return {
       id,
-      permalink: permalink(descriptor, { id, date }),
+      slug,
+      permalink: permalink(descriptor, { id, slug, date }),
       title: asString(frontmatter.title) ?? id,
       date,
       updated: asDate(frontmatter.updated),

package/src/lib/delivery/site-index.ts

@@ -0,0 +1,68 @@
+// cairn-cms: the site-level content index (dated-slug design). It unions every concept's
+// per-concept index into one cross-concept resolver: a single byPermalink map a catch-all route
+// matches a request path against, one entries() list the prerenderer walks, and the per-concept
+// indexes for concept-scoped archive, tag, and feed loaders. A duplicate permalink throws at build.
+import type { ConceptDescriptor } from '../content/types.js';
+import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
+
+/** One concept's descriptor paired with its built index. */
+export interface ConceptIndex {
+  descriptor: ConceptDescriptor;
+  index: ContentIndex;
+}
+
+/** The cross-concept query surface a catch-all route and the sitemap read. */
+export interface SiteIndex {
+  /** Resolve a request path (with or without a trailing slash) to its entry, or undefined. */
+  byPermalink(path: string): ContentEntry | undefined;
+  /** Newer/older neighbors within the entry's own concept, for prev/next links. */
+  adjacent(entry: ContentSummary): { newer?: ContentSummary; older?: ContentSummary };
+  /** Every entry's path across concepts, leading slash stripped, for SvelteKit `[...path]` prerender. */
+  entries(): { path: string }[];
+  /** One concept's index, for its archive, tag, and feed loaders. */
+  concept(id: string): ContentIndex | undefined;
+  /** Every non-draft summary across concepts, for the site-wide sitemap. */
+  all(): ContentSummary[];
+}
+
+/** Strip a trailing slash from a path, keeping the root "/" intact. */
+function normalizePath(path: string): string {
+  return path.length > 1 ? path.replace(/\/+$/, '') : path;
+}
+
+/** Union per-concept indexes into a site-level resolver; throw on a duplicate permalink. */
+export function createSiteIndex(concepts: ConceptIndex[]): SiteIndex {
+  const byPath = new Map<string, { index: ContentIndex; id: string }>();
+  const byId = new Map<string, ContentIndex>();
+  for (const { descriptor, index } of concepts) {
+    byId.set(descriptor.id, index);
+    for (const summary of index.all()) {
+      const existing = byPath.get(summary.permalink);
+      if (existing) {
+        throw new Error(
+          `site index: "${existing.id}" and "${summary.id}" both resolve to "${summary.permalink}"`,
+        );
+      }
+      byPath.set(summary.permalink, { index, id: summary.id });
+    }
+  }
+  return {
+    byPermalink(path) {
+      const hit = byPath.get(normalizePath(path));
+      return hit ? hit.index.byId(hit.id) : undefined;
+    },
+    adjacent(entry) {
+      const hit = byPath.get(entry.permalink);
+      return hit ? hit.index.adjacent(entry.id) : {};
+    },
+    entries() {
+      return [...byPath.keys()].map((p) => ({ path: p.replace(/^\//, '') }));
+    },
+    concept(id) {
+      return byId.get(id);
+    },
+    all() {
+      return concepts.flatMap(({ index }) => index.all());
+    },
+  };
+}