# Astro

> Astro project conventions — folder layout, styling system, asset and font pipelines, images, Scripts pipeline, Utils leaf layer, browser navigation. Use when working on pages, components, styles, scripts, assets, fonts, or visual testing in any Astro project in this org. Files come in three audiences (usage / pipeline-internals / architecture-debug) signalled by the filename — see the "File naming convention" section before opening anything.

- Skill: `jav-ed/astro-2` (Agent Skill, multi-file: 122 files)
- Install (CLI): `npx skillmds@latest add jav-ed/astro-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jav-ed/astro-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jav-ed (https://skillmd.com/u/jav-ed)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jav-ed/astro-2

---


# Astro

Dev server runs locally via `bun run dev`. Default Astro port is `4321`, but multi-app workspaces (this repo has Presence + Voice + Partner forks) shift each to its own port — check `astro.config.mjs` for the active project, or `ss -tlnp | grep 432` to find what's already running. Always use Bun — never npm or pnpm.

References are organised by shape. **Simple, single-concept areas** (file structure overview, assets, images) live as single files under `Areas/`. **Low-frequency or cross-cutting areas** that still belong to the Astro skill also live under `Areas/` as subfolders with an entry `linker_<Topic>.md` — currently `Areas/Language_Modes/`, `Areas/Hidden_Feartures/`, and `Areas/CI_CD/`. **Primary subsystems** that agents open often, or that grew into broad implementation domains, get promoted to a top-level folder with an entry `linker_<Topic>.md` — currently `Fonts/`, `Styles/`, `Design/`, `Niches/`, `Scripts/`, `Data/`, `Utils/`, `Content/`, `SEO/`, `Blog/`, `Legal/`, and `Debug_Validation/`. **Operational how-tos** live under `Tasks/`. **Operator-facing deliverables** and service runbooks live under `Services/`, currently AI image prompt briefs and self-hosted MapLibre map handoffs. **Canonical files to copy verbatim into projects** (configs, schema bases, recipe code) live under `Templates/` — the relevant `Areas/` or per-topic doc explains the WHY and points at the template by relative path. When a new subsystem needs documenting, decide which shape fits and place it accordingly.

## File naming convention — pick the right reader before opening

Docs in this skill are written for one of three readers, and the filename signals which. **Open the file that matches your job.** Reading the wrong-audience file wastes context on background you do not need (or, worse, makes you act on architecture trivia when you were just trying to ship a feature).

| Filename shape | Reader | What's inside |
|---|---|---|
| Plain name — `image.md`, `charts.md`, `assets.md`, `icons.md` | **Usage** — "I'm building features or content with this thing." | Rules, patterns, props tables, when-to-use-what guidance, surface-by-surface policies, common pitfalls. No machinery internals. The default. |
| `*_Pipeline.md` — `image_Pipeline.md`, `charts_Pipeline.md`, `diagrams_Pipeline.md`, `markdown_Pipeline.md` | **Pipeline internals** — "I'm modifying the build/render pipeline itself." | Regex passes, hook order, what-breaks-if-X-is-renamed contracts, porting checklists. Open only when actually editing the machinery. |
| Descriptive system name — `architecture.md`, `operations.md`, `performance.md` | **Architecture / debug** — "I'm reasoning about the system or debugging a tricky cross-cutting issue." | Why we chose this shape, system boundaries, ops runbooks, DevTools verification, lever rankings. Currently lives under `Areas/CI_CD/` and `Fonts/`. |

`_Pipeline` is reserved strictly for actual build/render pipeline internals. Architecture and debug docs use descriptive filenames and are surfaced by the relevant `linker_*.md`. When you find a file that mixes audiences, split it (one was `image_Pipeline.md`, now split into `image.md` + `image_Pipeline.md`) — don't leave the tangle for the next reader.

## Areas — per-subsystem deep dives

- [File structure](./Areas/file_Structure.md): thin `src/` overview — the three code locations (`src/Scripts/` for pipeline, `src/Utils/` for leaf layer, root `Code/` for manual CLI tooling), the leaf-layer rule, root `Code/` deep-dive, improved_Camel_Snake naming, English-first folder naming, numeric-prefix rules, high-level "where does a new file go?" routing table, add/rename checklists. Use for cross-cutting naming questions or as the entry point that routes to Scripts and Utils. The Scripts and Utils deep-dives live in their own folders.
- [Assets](./Areas/assets.md): `src/Assets/{Imgs,Fonts}/` folder layout, page/section subfolders under `Imgs/`, the three image-loading patterns (direct import, `import.meta.glob`, MDX), where local-font files live on disk, and rename/move checklist including the OG manifest path gotcha. Use when adding images or fonts (file placement), importing them into pages/components/MDX, or restructuring the assets tree.
- [Images (usage)](./Areas/image.md): when to reach for `<Picture>` vs `<Image>`, the picture policy by surface (blog prose → `Post_Img`; design heroes → `Hero_Picture`; blog covers → `Blog_Cover_Picture`; blog index thumbnails → `Blog_Row_Thumbnail_Picture`; cards/thumbnails/portraits; galleries with separate preview vs lightbox; wide editorial panels), the Partner picture audit listing current picture surfaces with their policy verdict, the AVIF + WebP format choice, the four-knob loading playbook (`loading` / `decoding` / `fetchpriority` / preload) with the LCP-critical extra steps, and the common-mistakes list. Use when adding images that need to be fast on mobile, fixing LCP regressions, or deciding whether a raw `<Picture>` call needs explicit `widths` / `sizes`. Complements `assets.md` (which covers file layout) and the Fonts area (which covers font preload).
- [Image pipeline (internals)](./Areas/image_Pipeline.md): the build-time machinery — how `<Picture>` expands to `<picture>` + `<source>` + `<img>`, the `image.breakpoints` config and the source-capping behaviour that justifies oversampling, the `layout: "constrained"` + `responsiveStyles: false` rationale (Tailwind fights Astro's inline styles), and the content-hashed cache under `.astro/`. Open this only when modifying breakpoints, debugging an unexpected emit, or porting the pattern to a new project. For author-facing usage open `image.md` instead.
- [AI image prompt](./Services/Ai_Img_Prompt/linker_Ai_Img_Prompt.md): write copy/paste-ready image prompt briefs under `Scratch/Img_Prompts/`; do not assume the agent is generating the image directly. Contains the universal content rules for every AI-generated source image — no faces of any living creature, no photo-like real-people/real-premises imagery, and the allowed-when-faceless catalogue — plus prompt-block structure, negative-prompt text, aspect-ratio guidance, and a complete Markdown example. Per-project flavor stays in `Project_Manag/Docs/Brand/imagery_Brief_*.md`. Use when preparing AI image prompts for the operator to paste into an image-generation tool.
- [Maps](./Services/Maps/linker_Maps.md): self-hosted MapLibre vector-map workflow — local/private tenant vs public tenant, tile/glyph/sprite/style ownership, tile-schema compatibility, visual style iteration, JSON export, and map-server handoff templates. Use when adding or changing a map surface, freezing a local style into hosted JSON, or coordinating CORS/static-asset requirements with the map-server operator.
- [Icons](./Areas/icons.md): Lucide-only policy, `@lucid/*` Vite alias wiring (tsconfig + astro.config), `Lucid_<Name>` component naming, sizing via Tailwind `size-*`, `currentColor` + `text-*` coloring, custom-SVG home at `src/Icons/<Category>/` and the two-rule explanation (`src/` vs `public/` gates SVGO; `Icons/` specifically is org convention, not SVGO requirement), inline `<svg>` exemption for data-driven geometry, SVGO config recipe, and the org-wide arrow convention (`arrow-right` internal / `arrow-up-right` external / `chevron-down` expand). Use when adding any icon, deciding where a custom SVG belongs, or wiring SVGO into a new project.
- [Page routes](./Areas/page_Routes.md): the `src/pages/` side of routing — `[lang]/` prefix idiom, the two framework-mandatory `index.astro` files (root `/`, lang-root `/{lang}/`) and why every other route uses a self-naming bracket file, English-named files with URL leaves read from `mdx_Info.slug` per language (never German file names like `kontakt.astro`), the bracket-file-plus-bracket-folder pattern for list + item routes (`[blog].astro` next to `[blog]/[post_Slug].astro`), the dispatcher-over-fan-out rule with `[legal_page].astro` and `[static_page].astro` as worked examples, the `getStaticPaths` and href-resolver helper tables (`build_Per_Lang_Index_Paths`, `build_Per_Lang_Slug_Paths`, `resolve_Top_Level_Page_Path`, `resolve_Top_Level_Entry_Path`, `build_Path`), the sitemap resolver in `page_File.ts` honoring both bracket-file and bracket+index layouts, plus add/rename checklists. Use when adding a new top-level route, restructuring an existing one, or debugging a sitemap-resolver miss. Pairs with [Slugs and IDs](./Content/slug_And_Id.md), which covers the content side of the same routing equation.

## Language Modes — single-lang vs multi-lang project shape

- [Language modes overview](./Areas/Language_Modes/linker_Language_Modes.md): entry point for every question where behavior changes based on `langs_Config.supported_Langs.length`. Routes to affected surfaces, multi-lang mode, and single-lang mode.
- [Affected surfaces](./Areas/Language_Modes/affected_Surfaces.md): the cross-surface checklist for language-mode changes — mandatory inputs, bare root, routing, content tree, SEO head, sitemap, lastmod, language switchers, and JSON-LD review items.
- [Multi-lang mode](./Areas/Language_Modes/multi_Lang_Mode.md): every real public page lives under `/<lang>/`; bare `/` is a deployment diagnostic with `noindex,nofollow` and server redirect ownership.
- [Single-lang mode](./Areas/Language_Modes/single_Lang_Mode.md): bare `/` is the real public landing page; hreflang and language switchers hide; `/<main_Lang>/` is redundant and excluded from the sitemap.

## Fonts — own folder (grew past one cohesive file)

- [Fonts overview](./Fonts/linker_Fonts.md): entry point for every font question. Routes to Bootstrap (project-setup view — the slot=category convention (Modern=sans, Elegant=serif, Precise=mono), the three real edit points, dependency map showing five consumers of `font_Config.js`, what auto-inherits at runtime vs. bakes at build with the Mermaid caveat, single-bundled-font and multi-font playbooks, project audit checklist), Setup (Astro Fonts API config, providers, cssVariable convention, variable chain, Tailwind preference, preload strategy, weights gotcha, checklists), Reader Settings (runtime size/spacing/font panel on blog — the `data-rs-*` button protocol, persistence, the inline-style-on-`article.prose` swap mechanism, accessibility), CJK rendering (negative-tracking ban, weight ceilings for OG, `b_Cjk` detection), and Performance & Debugging (what `<Font />` emits in HTML, DevTools verification, build output, cache invalidation, lever ranking). Use as the routing layer for any font work; the per-topic files do the heavy lifting.

## Styles — CSS organisation (own folder, grew past one cohesive file)

- [Styles overview](./Styles/linker_Styles.md): entry point for every CSS question. Owns the Tailwind-vs-CSS rule (Tailwind by default for element-local styling; CSS when it earns its keep as reusable primitives, CSS-only behavior, source-of-truth control, reduced duplication, motion handling, or cross-component chrome). Routes to folder_Structure (two-folder Base/ + Pages/<PageName>/ split, snake_Case + PascalCase naming, the entry-chain mechanics, the page-scoping pattern with worked examples from Partner), tokens (base semantic vars in `theme.css`, dependent color roles in `derived_Color_Vars.css`, `@theme inline` exports, `[data-theme="dark"]`, name-reserved tokens, full catalogue, pre-paint theme-attribute script, why oklch is mandatory), and layers_And_Breakpoints (`@layer base` / `components` / unlayered discipline, `@custom-variant` breakpoint conventions, three operational checklists for adding / renaming / lifting a stylesheet). Use as the routing layer for any Styles work; the per-topic files do the heavy lifting.

## Design — visual and interaction rules (own folder, grew past one cohesive file)

- [Design overview](./Design/linker_Design.md): entry point for premium visual-discipline questions. The editorial layer that governs *which* token to reach for in markup, separate from Styles which owns the token system and the Tailwind-vs-CSS implementation rule. Routes to colors (cardinal never-raw-colors rule, monochromatic-default rule, three-tier text hierarchy, full role-token reference, contrast traps), typography roles (display-vs-functional font strategy without prescribing universal serif/sans), CTAs (primary-action scarcity, secondary action hierarchy, focus-ring color), surfaces (derived section roles, section rhythm, card/grid limits, borders), interactions (`.surface-hover`, compact menu/icon chrome primitives, hover/focus/current/selected/disabled/open-state semantics), radius (three allowed steps plus pill, why only three, why the larger tokens exist but aren't for page work), links (three underline patterns — inline `border-b`, active nav `text-decoration`, active filter with `--primary` — plus the no-underline editorial arrow-link pattern and breadcrumb exception), icons (Lucide usage, arrow semantics, no text glyph arrows, icon sizing/color/hover behavior), motion (mandatory `prefers-reduced-motion` global override, flat-by-default elevation rule, transition discipline of 150–250ms / ease in-out / one property, scroll-driven-animation pattern with fallback, explicit anti-patterns), and audit checklist. Use as the routing layer for general premium design work. Dentist-specific rules and commercial dentist tiers live under Niches, not Design.

## Niches — domain-specific design guidance

- [Niches overview](./Niches/linker_Niches.md): domain-specific guidance that is reusable within a niche but not universal across Astro projects. It routes to Dentist register, typography, and dentist commercial-tier notes, and explains the boundary: conceptual domain rules here, actual brand values in project docs and token files, copyable code only in Templates.

## Scripts — pipeline/infrastructure code (own folder, six purpose subfolders)

- [Scripts overview](./Scripts/linker_Scripts.md): entry point for every Scripts question. The six purpose folders with their runtimes (build vs browser vs separate process), the leaf-layer rule, the `Code/` (root manual tooling) vs `src/Scripts/Build/` (Astro build pipeline) distinction, naming, decision table, add/rename checklist. Use as the entry point for any pipeline / build / browser-boot work, and as the principle source when bootstrapping a new repo's Scripts layer.
- [Astro_Frontmatter](./Scripts/astro_Frontmatter.md): build-time helpers called from inside `.astro` frontmatter — routing factories, lang providers, OG image naming, per-page data collectors. Internal Common/ + per-page subfolder pattern, Astro_Config/ for files imported by `astro.config.mjs`. Use when adding a build-time helper used by page templates.
- [Build](./Scripts/build.md): plugins/integrations wired into `astro.config.mjs` and `ec.config.mjs` — remark/rehype plugins, TextMate grammars for Expressive Code, standalone integrations (HTML minifier, meta-tag fixer). Use when adding a Markdown transform, syntax highlight grammar, or build-time post-processor.
- [Browser_Client](./Scripts/browser_Client.md): client-side hydrated JS organized by English page name (`Header/`, `Blog/`, `Contact/`, `Common/`). Three wiring patterns (eager import, `<script src>`, lazy `await import()`), internal relative imports for portable feature folders. Use when adding any code that runs in the user's browser.
- [Content_Schemas](./Scripts/content_Schemas.md): flat folder of Zod schemas — one per content collection plus shared `schema_Seo.ts`. Imported by `src/content.config.ts`. Naming, composition with the shared SEO schema, the numeric-suffix exception for ID-ranged collections. Use when adding or modifying a content collection's frontmatter shape.
- [Multi_Lang_Txts](./Scripts/multi_Lang_Txts.md): translation tables keyed by lang code, page/section/feature subfolder split, `Shared/route_Txt.ts` for structural route labels, `assert_Translation.ts` for build-time coverage validation. The crucial distinction from `Utils/Common/` language metadata (strings shown to users vs. facts about languages). Use when adding UI labels, route labels, page copy, or tooltips in multiple languages.
- [OG_Images (usage)](./Scripts/og_Images.md): the in-repo OG manifest builder — what lives in `src/Scripts/OG_Images/`, which project inputs live in `src/Data/Og_Img/`, the WebP output format, explicit split-icon config, how to wire `generate_Og_Manifest()` into `astro.config.mjs`, why the worker is external (heavy and isolated), what does NOT belong here (the `<meta og:image>` tag, font registration, static cards), naming conventions, and the add/rename checklist. Use when designing a new OG card template, configuring or troubleshooting a new project's OG generation, or coordinating an output-format change with the external renderer.
- [OG_Images pipeline (internals)](./Scripts/og_Images_Pipeline.md): the build-time machinery — which Astro hooks fire and in what order (`astro:config:setup` → `injectRoute` for the virtual `/og_Manifest.json` route → build → `astro:build:done` moves the JSON to `Cache/Og_Gen/`), the manifest payload shape (`meta` + `tasks`) and what each field carries, how font roles flow from `font_Config.js` through `og_Font_Roles` into font variant payloads, and how `find_Astro_Cached_Font` resolves files by globbing `.astro/fonts/` for `{cssVariable}-{weight}-{style}-{subset}-{contenthash}.woff2`. Open only when modifying `manifest_Integration.js` / `worker_Mn.js`, adding fields to the manifest payload (a contract change with the external renderer), or debugging a build that emits an empty or malformed manifest.

## Data — infrastructure constants (own folder, grew past one cohesive file)

- [Data overview](./Data/linker_Data.md): entry point for any infrastructure-constants question. `src/Data/` holds values that change when the project's *shape* changes (new language, new domain, new OG contract, new dev tool) — modified by project engineers, not by feature contributors. Routes to Common (language config + BCP codes + site domain + analytics IDs + preview/demo metadata, the derived-helpers-stay-in-Data exception, the "no functions" rule), Og_Img (OG template catalogue, output config, reusable asset roles, explicit split-icon choices, theme contract), and Dev (dev-only feature-flag pattern, the audit-boundary reason for a separate `Dev/` subfolder, the "all false before production" discipline, when NOT to use a dev flag — real feature flags belong in env vars, per-user toggles in settings, per-tenant toggles in customer-config repos). Includes the Data-vs-Utils mutability rule and a "Customer / tenant state" section that explicitly routes out to the project's customer-config flow (multi-tenant state does not live in `src/Data/`). Use as the routing layer for any Data work; the per-topic files do the heavy lifting.

## Utils — leaf-layer code (own folder, has its own subfolder structure)

- [Utils overview](./Utils/linker_Utils.md): what `src/Utils/` is for (leaf-layer code — shared data + pure helpers, imported by pages, components, layouts, and Scripts; never imports back), the leaf-layer rule (Utils is the bottom of the import graph), the two kinds of content (data files vs. pure helpers), subfolder convention (`Common/` always; `<Feature>/` per-project), naming, decision table, add/rename checklist. Use as the entry point for any Utils question, and as the principle source when bootstrapping a new repo's Utils layer.
- [Common/](./Utils/common.md): what site-wide content belongs in `Utils/Common/` (language metadata, owner contact, locale detection) vs. what does NOT (translation strings → `Scripts/Multi_Lang_Txts/`, page-specific data, DOM-touching code), file-pattern recommendations, honest note on Jav_Web's historical `helper.js` junk-drawer. Use when adding a site-wide constant or pure cross-cutting helper.
- [Feature subfolders](./Utils/feature_Utils.md): when to lift a helper into `Utils/<Feature>/` (the three thresholds — two callers in one feature, too-narrow for Common, multiple related helpers), Jav's `Blog/` as a clean worked example, Jav's `Overview/` as an honest counter-example of what NOT to copy, sub-subfolder rules, naming. Use when a feature accumulates shared helpers and you're deciding whether to promote them.

## Content — content-collection conventions (own folder, org-standard pattern + two project choices)

- [Content overview](./Content/linker_Content.md): entry point for any content-collection question. What Astro Content Collections solve, the three folders that cooperate (`src/Content/` for files, `src/Scripts/Content_Schemas/` for schemas, `src/content.config.ts` for registration), the org-standard pattern (flat `<lang>/` siblings + path-based ID + per-language `slug:` field), the two remaining per-project choices (folder naming, asset co-location), the prior-question file [Content vs Config vs Labels](./Content/content_Vs_Config_Vs_Labels.md) for choosing between MDX / `Data/Common` / `Multi_Lang_Txts` with an explicit gray-zone section, and a section pointing at the four `Content/Templates/` copy-paste artifacts. Use as the entry point and as the principle source when bootstrapping a new repo's content layer.
- [Folder structure](./Content/folder_Structure.md): `src/Content/<Collection>/` layout, the numeric-prefix-vs-plain-name decision with the project-count threshold for choosing, `NNNN_` entry-filename prefix for sort order, `Post_Assets/` co-location pattern and the glob-safety trade-off. Use when adding a collection folder or restructuring an existing one.
- [Multilingual organization](./Content/multilingual.md): the org-standard flat-language-siblings pattern (`{en,de,es,fr,zh}/` under each collection), why Caddy at the proxy layer makes Astro folder asymmetry unnecessary, the loader configuration, routing via path-split + frontmatter slug, adding translations, and a short legacy carve-out for Jav_Web's `000_Landing_Page` (the only collection still on `en/` + `translation/<lang>/` post the 2026-05-18 migration). Use when bootstrapping a multilingual project or migrating any remaining pre-migration collections.
- [Slugs and IDs](./Content/slug_And_Id.md): the ID-vs-URL-slug distinction, the standard path-based `generateId` + frontmatter `slug:` per language pattern, the `translation_key` concept (filename stem as stable cross-lang identifier), the URL-slug kebab-case regex, cross-language sister-entry lookup by filename match, the extension for URLs whose middle segments also localize (per-language structural-segment map + `build_Per_Lang_Slug_Paths` helper — Jav_Web's implementation in `route_Slugs.ts` / `per_Lang_Slug.ts`), and the landing-page legacy carve-out with migration steps. Use when designing a multilingual project's URLs, adding a collection with multi-segment localized paths, or migrating an inherited pre-migration collection.
- [Adding a new collection](./Content/add_New.md): end-to-end workflow checklist — apply the standard pattern, make the two per-project choices (folder naming, asset co-location), write the schema in `Scripts/Content_Schemas/`, register in `content.config.ts`, create the folder + first entry, wire to a page template via `getStaticPaths`, add translations, verify the build. Use as the operational playbook when introducing or removing a collection.
- [Schema patterns](./Content/schema_Patterns.md): six reusable Zod schema field patterns Partner has converged on — status enum for draft/published workflow, the `image()` helper and its function-form `schema: ({ image }) =>` footgun, cross-references via `translation_key` (filename, not slug) for cross-language stable links, `sort_key` override for non-default ordering (German umlauts, display-vs-sort name), surface/variant enum for one-template-many-looks, embedded structured frontmatter (FAQ + JSON-LD, sources/bibliography) for content that powers multiple consumers. Use when designing a new collection's schema or when an existing schema feels repetitive — these patterns let you stop re-inventing.

## SEO — discoverability and structured data (own folder, grew past one cohesive file)

- [SEO overview](./SEO/linker_Seo.md): entry point for every SEO question. The six surfaces that compose SEO and the boundary against adjacent areas (OG *image generation* lives in `Scripts/og_Images.md`; the `schema_Seo.ts` Zod is documented in `Scripts/content_Schemas.md` with a copy-paste template at `Templates/seo_Schema.ts`; per-language metadata lives in `Data/Common`). Routes to head_Tags (the full `<head>` block — title, description, OG with width/height/type/alt + locale:alternate, Twitter card, canonical, hreflang with two emission modes for translated-slug vs parallel-slug pages, x-default, sitemap link, theme-color light+dark, SVG+ICO favicon — plus the Layout prop contract and the strict head-order rules), JSON-LD (the per-type-builder pattern, the shared identity builder that keeps Person/Organization in sync across every schema, the `og_Type` dispatcher, the `extra_Schemas` escape hatch, a catalogue of which schema fits which page kind, per-type reference for Article/Profile/Website/Breadcrumb/FAQPage and domain schemas like LocalBusiness/MedicalProcedure, validation workflow, anti-patterns), and sitemap_And_Robots (`@astrojs/sitemap` integration with `filter` + `i18n` options, static vs dynamic robots.txt with the multi-language Disallow case that justifies dynamic). Includes bare-`/` handling by mode: multi-lang root diagnostic vs single-lang public landing. Includes a six-step bootstrap order for standing up SEO on a new project. Use as the routing layer for any SEO work; the per-topic files do the heavy lifting.

## Blog — long-form prose pages (own folder, grew past one cohesive file)

- [Blog overview](./Blog/linker_Blog.md): entry point for every blog-implementation question. The cohesive subsystem around `Post_Layout.astro` and its supporting cast, plus a strict boundary against adjacent areas (reader-settings panel → `Fonts/reader_Settings.md`; Article + Breadcrumb + FAQPage JSON-LD → `SEO/json_Ld.md`; frontmatter schema → `Content/schema_Patterns.md` + `Scripts/content_Schemas.md`; OG image generation → `Scripts/og_Images.md`; browser scripts under `Browser_Client/Blog/` → `Scripts/browser_Client.md`). Routes to `MDX_Components/` (component map, `Post_Img`, links/cards, structured blocks, code/tables), post_Covers, toc_And_Chrome, markdown_Pipeline, diagrams, charts, and typography. Includes an eight-step bootstrap order for standing up a blog on a new project. Use as the routing layer for any blog work; the per-topic files do the heavy lifting.

## Legal — public legal/demo compliance references (own folder)

- [Legal overview](./Legal/linker_Legal.md): entry point for Astro legal-page implementation references. Routes first by legal layer: real public-site operator pages, fictional demo/sample pages, and final client delivery pages. Covers persistent real-operator links, German dentist-preview legal pages, final client Impressum intake, §5 DDG as the federal Impressum baseline, state/chamber follow-up checks, source registers, and implementation footguns used when editing or auditing legal MDX/content. This is not legal advice; it is the technical/source checklist agents use before changing legal pages.

## CI/CD — deployment pipeline (low-frequency area folder)

- [CI/CD overview](./Areas/CI_CD/linker_CI_CD.md): working CI/CD skill area for deploying an Astro repo via Woodpecker CI to a Linux server behind Caddy. The pipeline shape is the same across every Astro repo we ship — `install → build → og_images → compress → deploy` — what varies per project is the deploy target, the repo path on the agent machine, and whether the Forgejo/Woodpecker trigger path is already active. Route platform questions to `.agents/skills/ci-cd/Platform/` for shared Forgejo/Woodpecker service checks, API discovery, and secrets. Route application questions to `.agents/skills/ci-cd/Application/` for repo integration, repo trigger checks/setup, active deploy use, rollback, and verification. Architecture remains the explanation for local backend, external scripts, `skip_clone: true`, release naming, atomic symlink swap, and footguns.

## Debug / Validation — cross-cutting error patterns (own folder)

- [Debug/Validation overview](./Debug_Validation/linker_Debug_Validation.md): entry point for catching errors early and hard. The org does not use `interface Props {}` — ArkType replaces it with runtime validation that actually crashes. Routes to props_Validation (the full ArkType pattern — `ark_Type` import, `props_Schema`, `props_Result`, explicit `instanceof ark_Type.errors` check, naming conventions, when to apply, the deliberate-crash test technique). Use when adding props to any Astro component or layout, or when a confusing downstream crash needs tracing back to its real source.

## Hidden Features — fallback and rarely-seen user surfaces (low-frequency area folder)

- [Hidden Features overview](./Areas/Hidden_Feartures/linker_Hidden_Feartures.md): entry point for user-facing fallback surfaces that normal navigation does not expose but that still need production quality. Currently routes to [Custom 404 pages](./Areas/Hidden_Feartures/404/linker_404.md), covering Astro route files, multilingual copy placement, noindex/sitemap exclusion, Caddy `handle_errors`, localized error bodies, expected failure modes, and a copyable Caddy template.

## Tasks — operational how-tos

- [Browser navigation](./Tasks/browser_Nav.md): playwright-cli usage, dev-server discovery, where to store screenshots in `Scratch/`. Use when the task requires opening a page in a browser, taking screenshots, or running visual diffs.
- Accessibility audit — use the `audit_Jav` skill instead. Lives outside this skill because it has its own CLI surface.

## Templates — canonical files to copy verbatim

Real source files an agent can drop directly into a project. Each template has its WHY documented in the corresponding `Areas/` or per-topic doc — the template file is the artifact, the doc is the rationale. Templates are the source of truth: if a project needs to deviate, update the template first (with reasoning in the file header), then copy out.

- [`Templates/svgo_Config.ts`](./Templates/svgo_Config.ts) — SVGO configuration for Astro's `experimental.svgo`. Copy to `src/Scripts/Astro_Frontmatter/Astro_Config/svgo_Config.ts`. Rationale and per-plugin reasoning in [Icons § SVGO config](./Areas/icons.md).
- [`Templates/seo_Schema.ts`](./Templates/seo_Schema.ts) — Zod `seo_Schema` composed into every content collection's frontmatter (title, description, and required `og_Img`). Copy to `src/Scripts/Content_Schemas/schema_Seo.ts`. Rationale and composition pattern in [Content_Schemas](./Scripts/content_Schemas.md); how the consumed fields surface in `<head>` is in [SEO § head tags](./SEO/head_Tags.md).
- [`Templates/og_Img_Schema.ts`](./Templates/og_Img_Schema.ts) — Zod `og_Img_Schema` for generated OG image copy, optional `template_Override`, and optional `image` source for deliberately image-led cards. Copy to `src/Scripts/Content_Schemas/schema_Og_Img.ts` when a project uses the `Data/Og_Img` OG pipeline.