Trim always-loaded Claude context and add llm-docs discovery (#14701)

cderv · web-flow · commit d31f704700a5 · 2026-07-16T17:28:30.000+02:00
Trim always-loaded Claude context and add llm-docs discovery

Reduce the baseline token cost of every Claude Code session on the
repo, and make the llm-docs/ architecture deep-dives discoverable.
The always-loaded .claude/CLAUDE.md had grown well past the ~200-line
guidance for memory files, and the llm-docs/ docs had no mechanism
steering a reader to the relevant one for a given task.

- Compress .claude/CLAUDE.md from 276 to 79 lines, removing only
  codebase-derivable prose and content duplicated by the rule files
- Add a one-line discovery pointer from a path-scoped .claude/rules/
  file to each llm-docs/*.md, scoped to the doc's own source so it
  loads lazily and never fires on unrelated work
- Add small dedicated rules for topics with no narrow existing rule:
  revealjs, axe, callout, localization, quarto-api, pandoc
  templates, preview, publishing, code signing
- Have CLAUDE.md instruct consulting llm-docs/ directly when planning
  or investigating, since path-scoped pointers only fire once a
  matching file is open
- Converge duplicated rule content to single sources and record the
  discovery-pointer convention in llm-docs-maintenance.md
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
diff --git a/.claude/rules/filters/overview.md b/.claude/rules/filters/overview.md
@@ -68,19 +68,7 @@ Reach for it when a Pandoc *parsing* behavior must change before any filter can
 
 ## Debugging
 
-**Filter tracing (recommended):**
-```bash
-# Linux/macOS
-package/dist/bin/quarto dev-call show-ast-trace document.qmd
-
-# Windows
-package/dist/bin/quarto.cmd dev-call show-ast-trace document.qmd
-```
-
-**AST diagram:**
-```bash
-quarto dev-call make-ast-diagram document.qmd
-```
+Visualize filter transformations with the `dev-call` tools `show-ast-trace` (interactive trace viewer) and `make-ast-diagram` (static AST diagram) — see `.claude/rules/dev-tools/dev-call-commands.md` for both.
 
 ## Related Documentation
 
diff --git a/.claude/rules/formats/axe-accessibility.md b/.claude/rules/formats/axe-accessibility.md
@@ -0,0 +1,12 @@
+---
+paths:
+  - "src/format/html/format-html-axe*"
+  - "src/resources/**/*axe*"
+  - "tests/integration/playwright/tests/*axe*"
+---
+
+# Axe Accessibility Checks
+
+For the axe-core integration architecture across build-time TypeScript, compile-time SCSS, and runtime JS layers, see `llm-docs/axe-accessibility-architecture.md`.
+
+For the axe accessibility testing workflow (scan config, runtime DOM markers, output-mode patching), see `llm-docs/axe-accessibility-testing.md`.
diff --git a/.claude/rules/formats/callout-styling.md b/.claude/rules/formats/callout-styling.md
@@ -0,0 +1,11 @@
+---
+paths:
+  - "src/resources/formats/**/*callout*"
+  - "src/resources/filters/**/callout*"
+---
+
+# Callout Styling
+
+For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`.
+
+The shared SCSS where callout CSS lives (`_bootstrap-rules.scss`, `revealjs/quarto.scss`) is covered by the `sass-theming` rule, which also points to this doc.
diff --git a/.claude/rules/formats/pandoc-templates.md b/.claude/rules/formats/pandoc-templates.md
@@ -0,0 +1,12 @@
+---
+paths:
+  - "src/resources/formats/pdf/pandoc/**"
+  - "src/resources/formats/typst/pandoc/**"
+  - "package/src/common/update-pandoc.ts"
+---
+
+# Pandoc Templates (LaTeX & Typst)
+
+For how Pandoc's LaTeX templates are copied into Quarto and restructured into a modular form (`latex.template`, `latex.common`, …), see `llm-docs/pandoc-quarto-latex-templates.md`.
+
+For the equivalent Typst template integration (`typst.template`, `template.typst`), see `llm-docs/pandoc-quarto-typst-templates.md`.
diff --git a/.claude/rules/formats/revealjs.md b/.claude/rules/formats/revealjs.md
@@ -0,0 +1,9 @@
+---
+paths:
+  - "src/format/reveal/**"
+  - "src/resources/formats/revealjs/**"
+---
+
+# RevealJS Format
+
+For reveal.js format internals — metadata normalization, the two template files (`revealjs.template` vs `template.html`), and the TypeScript/Pandoc division of responsibility — see `llm-docs/revealjs-format-architecture.md`.
diff --git a/.claude/rules/formats/sass-theming.md b/.claude/rules/formats/sass-theming.md
@@ -20,3 +20,5 @@ background-color: var(--r-background-color, $body-bg);
 ```
 
 Read `llm-docs/sass-theming-architecture.md` for full compilation pipeline details.
+
+For the three-tier callout CSS architecture (Bootstrap, RevealJS, standalone HTML), see `llm-docs/callout-styling-html.md`.
diff --git a/.claude/rules/llm-docs-maintenance.md b/.claude/rules/llm-docs-maintenance.md
@@ -55,3 +55,11 @@ They are NOT:
 - User documentation (that's at quarto.org)
 - Code comments (those live in source files)
 - Issue-specific notes (those go in PR descriptions)
+
+## Discovery Pointers
+
+So a relevant deep-dive actually gets read when a matching task comes up, each `llm-docs/*.md` should be reachable from a **discovery pointer** — a one-line "see `llm-docs/<file>.md`" reference — placed inside a path-scoped rule under `.claude/rules/` whose `paths:` frontmatter matches the doc's own source files. This reuses the existing lazy-load gate at zero baseline context cost.
+
+Granularity rule: the pointer inherits its host rule's `paths:`, so it must live in a rule scoped **no broader than the doc's topic** — otherwise it loads on unrelated work (a reveal.js pointer does not belong in a rule scoped to all of `src/format/**`). If the best existing rule is too generic, create a small dedicated rule scoped to that doc's source instead.
+
+**When adding a new `llm-docs/*.md`:** add its discovery pointer to a matching path-scoped rule, or create a narrowly-scoped rule for it.
diff --git a/.claude/rules/packaging/code-signing.md b/.claude/rules/packaging/code-signing.md
@@ -0,0 +1,14 @@
+---
+paths:
+  - "package/src/macos/installer.ts"
+  - "package/src/windows/installer.ts"
+  - "package/scripts/macos/entitlements.plist"
+  - "package/scripts/macos/distribution.xml"
+  - ".github/workflows/create-release.yml"
+  - ".github/workflows/actions/keychain/action.yml"
+  - ".github/workflows/actions/sign-files/action.yml"
+---
+
+# Code Signing for Installers
+
+For how release installers get signed and notarized on macOS and Windows (Gatekeeper, SmartScreen, and the keychain/signing actions in `create-release.yml`), see `llm-docs/code-signing-installers.md`.
diff --git a/.claude/rules/preview/overview.md b/.claude/rules/preview/overview.md
@@ -0,0 +1,10 @@
+---
+paths:
+  - "src/command/preview/**"
+  - "src/project/serve/**"
+  - "src/preview/**"
+---
+
+# Preview System
+
+For how `quarto preview` works end-to-end — CLI entry, the branching logic in `cmd.ts`, single-file vs project preview lifecycle, and file watching — see `llm-docs/preview-architecture.md`.
diff --git a/.claude/rules/publishing/overview.md b/.claude/rules/publishing/overview.md
@@ -0,0 +1,9 @@
+---
+paths:
+  - "src/publish/**"
+  - "src/command/publish/cmd.ts"
+---
+
+# Publishing System
+
+For how `quarto publish` works internally — the `PublishProvider` interface, account management, and the end-to-end publish flow — see `llm-docs/publishing-architecture.md`.
diff --git a/.claude/rules/rendering/localization.md b/.claude/rules/rendering/localization.md
@@ -0,0 +1,9 @@
+---
+paths:
+  - "src/core/language.ts"
+  - "src/resources/language/**"
+---
+
+# Localization
+
+For how localized strings flow from `_language.yml` through metadata merging into Pandoc templates and the crossref/authors/callouts Lua filters, see `llm-docs/localization-architecture.md`.
diff --git a/.claude/rules/rendering/render-pipeline.md b/.claude/rules/rendering/render-pipeline.md
@@ -86,6 +86,8 @@ if (context?.config && isProjectInputFile(path, context)) {
 }
 ```
 
+For the full synthetic project mechanism (`projectContextForDirectory()`) and why two single-file code paths exist, see `llm-docs/synthetic-project-context.md`.
+
 ## Format Resolution
 
 Metadata merges in this order (later overrides earlier):
diff --git a/.claude/rules/schemas/zod-usage.md b/.claude/rules/schemas/zod-usage.md
@@ -59,9 +59,4 @@ YAML schema validation happens at config load time, so downstream code doesn't n
 
 ## Regenerating Schemas
 
-After modifying YAML schema definitions:
-
-```bash
-package/dist/bin/quarto dev-call build-artifacts    # Linux/macOS
-package/dist/bin/quarto.cmd dev-call build-artifacts  # Windows
-```
+After modifying YAML schema definitions, run `dev-call build-artifacts` — see `.claude/rules/dev-tools/dev-call-commands.md` § build-artifacts.
diff --git a/.claude/rules/testing/smoke-all-tests.md b/.claude/rules/testing/smoke-all-tests.md
@@ -63,6 +63,8 @@ _quarto:
         - ['\\begin\{figure\}']
 ```
 
+**Details:** `llm-docs/ensure-pdf-text-positions.md` — the `ensurePdfTextPositions` verification function for asserting spatial text-position relationships in tagged PDFs (Typst only; LaTeX not yet supported).
+
 ### Regex Match Array Format
 
 `ensureFileRegexMatches` (and variants like `ensureTypstFileRegexMatches`, `ensureLatexFileRegexMatches`) takes two arrays:
diff --git a/.claude/rules/testing/typescript-tests.md b/.claude/rules/testing/typescript-tests.md
@@ -22,11 +22,7 @@ TypeScript-based tests using Deno. Smoke tests render documents; unit tests veri
 
 ## Core Infrastructure
 
-| File | Purpose |
-|------|---------|
-| `tests/test.ts` | `testQuartoCmd()`, `testRender()`, `unitTest()` |
-| `tests/verify.ts` | Verification functions (`noErrors`, `fileExists`, etc.) |
-| `tests/utils.ts` | `docs()`, `outputForInput()`, path utilities |
+Core test files (`test.ts`, `verify.ts`, `utils.ts`) are described in `.claude/rules/testing/overview.md` § Core Files.
 
 ### Search for an existing verifier before writing one
 
diff --git a/.claude/rules/typescript/deno-essentials.md b/.claude/rules/typescript/deno-essentials.md
@@ -92,3 +92,5 @@ Common directives (use sparingly):
 3. **Import from deno_ral** - Not directly from std library
 4. **Use Deno APIs** - No Node.js equivalents
 5. **Prefer sync APIs** - Simpler code flow for CLI
+
+For the `error()` / `warning()` / `info()` one-line message-formatting convention, see `llm-docs/error-messages.md`.
diff --git a/.claude/rules/typescript/quarto-api.md b/.claude/rules/typescript/quarto-api.md
@@ -0,0 +1,9 @@
+---
+paths:
+  - "src/core/api/**"
+  - "packages/quarto-types/**"
+---
+
+# Quarto API
+
+For adding or modifying methods in the Quarto API (`src/core/api/`, `packages/quarto-types/`) consumed by external execution engines, see `llm-docs/quarto-api.md`.
