sveld 0.36.10 → 0.37.0

package/README.md

@@ -9,9 +9,9 @@ The goal is to get third-party Svelte libraries working with the Svelte Language
 
 [Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata.
 
-`sveld` uses the Svelte 5 compiler to parse `.svelte` files. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, and Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …). It also covers Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).
+`sveld` parses `.svelte` files with its own template parser (`src/template-parse/`), kept in parity with `svelte/compiler`'s parser by a differential test suite. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, and Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …). It also covers Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).
 
-For `lang="ts"` components, `sveld` keeps source-level prop type annotations when it can, instead of forcing JSDoc. That covers legacy `export let` props, typed `$props()` destructuring, typed whole-object `$props()` captures, local `interface`/`type` declarations, and imported type references in emitted `.d.ts` files.
+For `lang="ts"` components, `sveld` keeps source-level prop type annotations when it can, instead of forcing JSDoc. That covers legacy `export let` props, typed `$props()` destructuring (whole-object and per-prop), local `interface`/`type`/`enum` declarations, and TypeScript signatures on accessor exports (`export function`). Any type a prop annotation or accessor signature depends on — whether imported with `import type` or as a plain value import used only in a type position — is re-emitted as an `import type` at the top of the generated `.d.ts`, and local `interface`/`type`/`enum` declarations it depends on are copied alongside it. Everything stays textual: no semantic expansion, and `satisfies`/`as` are treated alike. A `const enum` is widened to a literal union of its member values instead of being re-declared, since `const enum` isn't supported by common bundlers under `isolatedModules`.
 
 By default, generated `.d.ts` files extend `SvelteComponentTyped` from `svelte`, so TypeScript and the Svelte Language Server work whether consumers use Svelte 3, Svelte 4, or Svelte 5. Set `typesOptions.format: "component"` to instead emit the Svelte 5 `Component` type; see [`typesOptions.format`](#typesoptionsformat).
 
@@ -125,6 +125,9 @@ export default class Button extends SvelteComponentTyped<
   - [Persistent parse cache (`cache`)](#persistent-parse-cache-cache)
   - [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples)
   - [Type inference diagnostics](#type-inference-diagnostics)
+    - [Diagnostic codes](#diagnostic-codes)
+    - [Severity and `--strict=errors`](#severity-and---stricterrors)
+    - [Ignoring diagnostics](#ignoring-diagnostics)
 - [Requirements](#requirements)
 - [Usage](#usage)
   - [Installation](#installation)
@@ -132,6 +135,7 @@ export default class Button extends SvelteComponentTyped<
   - [CLI](#cli)
   - [Exit codes](#exit-codes)
   - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
+  - [CI: strictness profiles (`--strict=ci`/`--strict=local`)](#ci-strictness-profiles---strictci---strictlocal)
   - [Node.js](#nodejs)
   - [Browser](#browser)
   - [Config File](#config-file)
@@ -141,18 +145,30 @@ export default class Button extends SvelteComponentTyped<
 - [JSON Output](#json-output)
 - [Custom Elements Manifest](#custom-elements-manifest)
   - [Consuming the manifest](#consuming-the-manifest)
+- [llms.txt Output](#llmstxt-output)
+- [Custom Writers](#custom-writers)
+  - [The `OutputWriter` contract](#the-outputwriter-contract)
+  - [Registering a writer](#registering-a-writer)
+  - [Running it via the plugin](#running-it-via-the-plugin)
+  - [Worked example: a `components.txt` name-list writer](#worked-example-a-componentstxt-name-list-writer)
 - [API Reference](#api-reference)
   - [reactive](#reactive)
   - [binding](#binding)
   - [@type](#type)
   - [@default](#default)
   - [@typedef](#typedef)
+  - [@property](#property)
   - [@callback](#callback)
   - [@slot / @snippet](#slot--snippet)
     - [Extra JSDoc tags before `@slot`](#extra-jsdoc-tags-before-slot)
     - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
   - [@event](#event)
+  - [@ignore / @internal](#ignore--internal)
   - [@deprecated](#deprecated)
+  - [@since](#since)
+  - [@see](#see)
+  - [@link](#link)
+  - [@example](#example)
   - [Context API](#context-api)
   - [@restProps](#restprops)
   - [@extendProps](#extendprops)
@@ -166,7 +182,7 @@ export default class Button extends SvelteComponentTyped<
 
 ## Approach
 
-`sveld` uses the Svelte compiler to statically analyze exported components and emit docs for consumers.
+`sveld` statically analyzes exported components and emits docs for consumers. Template parsing runs through sveld's own parser rather than `svelte/compiler`; `svelte/compiler` is imported only for its types, and `svelte/package.json` is read for the installed Svelte version. A differential test (`tests/svelte-template-parse-shim.test.ts`) parses every fixture `.svelte` file with both parsers and asserts the resulting ASTs match, and a weekly `svelte-canary` workflow re-runs that comparison against `svelte@latest` ahead of the lockfile pin.
 
 It extracts:
 
@@ -282,7 +298,7 @@ Without `resolveTypes`, JSON lists no props. With it, each field shows up with `
 }
 ```
 
-**Performance.** Off by default. This is the only path that loads TypeScript. It needs `typescript` and a `tsconfig.json`, runs slower than the AST-only pipeline, and gets slower as your types grow. Use it only when you need expanded JSON. `.d.ts` output is unchanged.
+**Performance.** Off by default. This is one of the two paths that load TypeScript. It needs `typescript` 7+ and a `tsconfig.json` (see [Requirements](#requirements)); if either is missing, `resolveTypes` fails the run instead of silently producing empty props. It also runs slower than the AST-only pipeline and gets slower as your types grow. Use it only when you need expanded JSON. `.d.ts` output is unchanged.
 
 ### Persistent parse cache (`cache`)
 
@@ -298,7 +314,7 @@ If a component [`@extendProps`](#extendprops) / [`@extends`](#extendprops) anoth
 
 ### Compile-checked `@example` blocks (`checkExamples`)
 
-`@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to run plain TS/JS `@example` blocks through the TypeScript program. Broken examples show up as `example-compile-error` diagnostics.
+`@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to check them: plain TS/JS bodies run through the TypeScript program, and `svelte`/`html` bodies run through sveld's own template parser. Broken examples show up as `example-compile-error` (TS/JS) or `example-syntax-error` (markup) diagnostics.
 
 ```ts
 await sveld({ json: true, checkExamples: true });
@@ -329,15 +345,23 @@ If `formatValue` is later renamed and the example is never updated, `checkExampl
     - Line 1: Cannot find name 'formatValue'.
 ```
 
-Plain TS/JS only. Examples fenced as `svelte` or `html`, or bare markup like `<Button />`, are skipped. Checking those needs `svelte2tsx` or similar, and sveld stays AST-only.
+A `svelte`/`html`-fenced example is syntax-checked, not type-checked: sveld parses the markup and discards the AST, so it catches malformed markup (a mismatched closing tag, an unterminated attribute) but not a prop that doesn't exist or a type error inside an expression. Those still need `svelte-check` in the consumer's own tests. Bare unfenced markup (`<Button />` with no code fence) is skipped either way.
 
-The check is narrow on purpose. It catches renamed or removed symbols and wrong argument counts. It is not full type checking and never pulls in types sveld cannot see.
+```
+@example blocks that failed to parse (1):
+  ./Component.svelte
+    - Line 1: sveld: invalid closing tag </span>.
+```
+
+The TS/JS check is narrow on purpose too. It catches renamed or removed symbols and wrong argument counts. Neither path is full type checking, and neither pulls in types sveld cannot see.
 
-Needs `typescript` and a `tsconfig.json`, same as `resolveTypes`. Use `--strict` (or the `strict` option) to fail CI when an example breaks.
+The TS/JS path needs `typescript` 7+ and a `tsconfig.json`, same as `resolveTypes` (see [Requirements](#requirements)); missing either fails the run rather than silently skipping every example. The markup path needs neither: pass `checkExamples: "syntax"` to run only it, so a project with only `svelte`/`html` examples (or no `tsconfig.json`) never loads TypeScript. Use `--strict` (or the `strict` option) to fail CI when an example breaks.
 
 ### Type inference diagnostics
 
-`sveld` collects unresolved-type diagnostics on every run: props that fall back to `any`, context values typed as `any`, `@event` tags with no dispatch or callback, `$props()`/`{@render}` syntax sveld can't model, and (when `checkExamples` is enabled) `example-compile-error`. They are always returned from the programmatic `sveld()` API in `SveldResult.diagnostics`. Each diagnostic carries an optional `source` range (the same `{ start: { line, column }, end: { line, column } }` shape as JSON output source ranges) whenever the parser holds a stable position for it.
+`sveld` collects unresolved-type diagnostics on every run: props that fall back to `any`, context values typed as `any`, `@event` tags with no dispatch or callback, `$props()`/`{@render}` syntax sveld can't model, and (when `checkExamples` is enabled) `example-compile-error`/`example-syntax-error`. They are always returned from the programmatic `sveld()` API in `SveldResult.diagnostics`. Each diagnostic carries an optional `source` range (the same `{ start: { line, column }, end: { line, column } }` shape as JSON output source ranges) whenever the parser holds a stable position for it.
+
+A prop with no type annotation, no `@type` JSDoc, and no initializer has nothing to infer a type or a default from: its JSON `type` stays absent (`"typeSource": "unknown"`), it triggers a `prop-unknown-type` diagnostic, and the emitted `.d.ts` types it as `any` with no `@default` line (rather than the literal type `undefined`).
 
 With `reportDiagnostics` or `strict`, the grouped summary looks like this:
 
@@ -346,28 +370,32 @@ sveld: 5 unresolved types found.
 
 Props without inferred types (1):
   ./icons/Add.svelte
-    - Prop "title" type could not be inferred; falling back to "any". (./icons/Add.svelte:4:2)
+    - Prop "title" type could not be inferred; falling back to "any". (./icons/Add.svelte:4:2) [sveld/prop-unknown-type]
 
 Context values typed as `any` (1):
   ./ThemeProvider.svelte
-    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any". (./ThemeProvider.svelte:8:6)
+    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any". (./ThemeProvider.svelte:8:6) [sveld/context-any-type]
 
 @event tags with no dispatch or callback (2):
   ./Modal.svelte
-    - @event "open" has no matching dispatch or callback prop. (./Modal.svelte:3:5)
-    - @event "close" has no matching dispatch or callback prop. (./Modal.svelte:4:5)
+    - @event "open" has no matching dispatch or callback prop. (./Modal.svelte:3:5) [sveld/event-no-source]
+    - @event "close" has no matching dispatch or callback prop. (./Modal.svelte:4:5) [sveld/event-no-source]
 
 Component syntax sveld skipped (1):
   ./Tabs.svelte
-    - {@render tabs(getTabProps())} argument is not a plain object literal; the render call was not mapped to slot metadata. (./Tabs.svelte:6:4)
+    - {@render tabs(getTabProps())} argument is not a plain object literal; the render call was not mapped to slot metadata. (./Tabs.svelte:6:4) [sveld/syntax-skipped]
 ```
 
-When `checkExamples` is also enabled, `@example` compile failures appear as a fifth group:
+When `checkExamples` is also enabled, `@example` failures appear as additional groups: TS/JS failures under `example-compile-error`, `svelte`/`html` failures under `example-syntax-error`.
 
 ```
 @example blocks that failed to compile (1):
   ./Component.svelte
-    - Line 1: Cannot find name 'formatValue'.
+    - Line 1: Cannot find name 'formatValue'. [sveld/example-compile-error]
+
+@example blocks that failed to parse (1):
+  ./Component.svelte
+    - Line 1: sveld: invalid closing tag </span>. [sveld/example-syntax-error]
 ```
 
 By default, nothing is printed. Opt in when you are working on types or want CI output:
@@ -391,11 +419,94 @@ npx sveld --json --strict
 
 `--check` is separate: it diffs `COMPONENT_API.json` for API drift and semver classification, not inference warnings.
 
+#### Diagnostic codes
+
+Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongside the older `kind`, so CI config and `diagnostics.ignore` matchers (below) have something that won't shift if the human-readable `message` text changes:
+
+| Code | Severity | Fix |
+| --- | --- | --- |
+| `sveld/prop-unknown-type` | `warning` | Add a native TypeScript annotation, a `@type` JSDoc tag, or an initializer sveld can infer a type from. |
+| `sveld/context-any-type` | `warning` | Annotate the `setContext` value's declaration with `@type` or a native TypeScript type. |
+| `sveld/slot-missing-type` | `warning` | Add the required `{Type}` annotation to the `@slot`/`@snippet` tag (e.g. `@slot {{}} name`); until then it falls back to `Record<string, never>`. |
+| `sveld/event-no-source` | `warning` | Dispatch the event (`createEventDispatcher`/`dispatch`), forward it (`on:name`), or add a matching `on<Name>` callback prop; otherwise remove the stale `@event` tag. |
+| `sveld/example-compile-error` | `error` | Fix the `@example` TS/JS code block so it type-checks, or remove the broken example. |
+| `sveld/example-syntax-error` | `error` | Fix the `@example` `svelte`/`html` markup so it parses, or remove the broken example. |
+| `sveld/syntax-skipped` | `error` | Rewrite the flagged syntax in a form sveld can model (see the diagnostic's `message` for what was skipped). |
+| `sveld/rest-props-unresolved` | `warning` | Spread `$$restProps` onto a plain element (or `svelte:element`) instead of a component, or add an `@restProps` tag to type it manually. |
+| `sveld/context-duplicate-key` | `warning` | Remove the duplicate `setContext` call, or give it a distinct key; only the first call's shape is used. |
+| `sveld/spread-unresolved` | `warning` | Spread a local object literal or a variable with a resolvable type instead; otherwise the spread widens the generated type to `Record<string, any>`. |
+| `sveld/export-unresolved` | `warning` | Export a local declaration directly instead of re-exporting an import or a binding from another file; sveld only resolves exports of a local declaration. |
+| `sveld/extend-props-target-missing` | `error` | Point `@extends`/`@extendProps` at a file that exists, and (for a bundled `.svelte` target) name its generated `<Name>Props` interface exactly. |
+| `sveld/extend-props-duplicate` | `warning` | Remove the extra `@extends`/`@extendProps` tag; only the last one is used. |
+| `sveld/extend-props-override` | `warning` | Rename the own prop, or accept that it intentionally overrides the `@extends` target's prop of the same name. |
+| `sveld/jsdoc-unknown-tag` | `warning` | Fix the tag name if it's a typo (e.g. `@depreacted` → `@deprecated`); otherwise no action needed, the tag still passes through unchanged. Only surfaced under `--strict`/`--report-diagnostics`. |
+| `sveld/typedef-duplicate` | `warning` | Rename one of the `@typedef`/`@callback` declarations; only the later one is kept. |
+| `sveld/property-duplicate` | `warning` | Remove the duplicate `@property`; only the later one is kept. |
+| `sveld/generics-conflict` | `warning` | Rename one of the `@generics`/`@template` declarations to a distinct generic name. |
+| `sveld/jsdoc-tag-dropped` | `warning` | Move the tag next to a `@slot`/`@snippet`/`@event`/`@typedef`/`@callback` tag in the same comment block so it has something to attach to. |
+| `sveld/internal-typedef-referenced` | `error` | Remove `@internal`/`@ignore` from the referenced typedef, or stop referencing it from public type text (inline the shape, or make the referencing item `@internal` too). |
+
+#### Severity and `--strict=errors`
+
+Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `jsdoc-tag-dropped` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
+
+```sh
+npx sveld --json --strict=errors
+```
+
+```ts
+await sveld({ json: true, strict: "errors" });
+```
+
+#### Ignoring diagnostics
+
+Two ways to suppress a diagnostic without disabling `strict` for the whole run. Either way, the diagnostic still appears in `SveldResult.diagnostics` (with `ignored: true`) and is still counted in the text summary (`sveld: 2 unresolved types found (1 ignored).`), but never fails `--strict` / `--strict=errors`.
+
+**Config matchers** (`diagnostics.ignore`, an array of `{ code?, component?, name? }`): every field you set on a matcher must match for it to apply; an omitted field matches anything. `component` is a glob (`*` within a path segment, `**` across segments):
+
+```ts
+// sveld.config.js
+export default defineConfig({
+  diagnostics: {
+    ignore: [
+      // Every prop-unknown-type diagnostic under legacy/.
+      { code: "sveld/prop-unknown-type", component: "./legacy/**" },
+      // One named symbol, anywhere.
+      { name: "internalOnly" },
+    ],
+  },
+});
+```
+
+**Inline `@sveld-ignore <code>`**, on the same JSDoc comment as the prop, `@event` tag, or context variable it applies to:
+
+```svelte
+<script>
+  /**
+   * @sveld-ignore sveld/prop-unknown-type
+   */
+  export let value;
+</script>
+```
+
+```svelte
+<script>
+  /**
+   * @event {CustomEvent<null>} legacyEvent
+   * @sveld-ignore sveld/event-no-source
+   */
+  export let label;
+</script>
+```
+
+A bare `@sveld-ignore` (no code) suppresses every diagnostic for that symbol.
+
 ## Requirements
 
-- Node 22+. CI tests against Node 22 on Linux, Windows, and macOS; earlier LTS versions are not verified.
+- Node 22+ if your config is `sveld.config.js` or `sveld.config.mjs` — `sveld` declares no `engines.node` floor. A `sveld.config.ts` file loads via a raw `import()`, with no transpile step, so it only works if the runtime strips TypeScript itself: on Node this needs unflagged type stripping (Node 22.18 / 23.6+; on older Node 22 patches it's behind `--experimental-strip-types`, so use a `.js`/`.mjs` config instead), which is why Node 24 — the first current major where type stripping is always on — is the only reason to require it. Bun (see `.bun-version`) loads `.ts` configs without Node at all. CI runs on Bun and does not pin a Node version; the release workflow pins Node 24 for `actions/setup-node` on the npm publish job only, not a requirement for consumers.
 - `sveld` is ESM-only. `require("sveld")` does not work — use `import` or dynamic `import()`.
-- `sveld` bundles its own Svelte 5 compiler to parse `.svelte` files. Parsing does not depend on the Svelte version installed in your project, so Svelte 3 and Svelte 4 codebases parse the same way Svelte 5 codebases do — there is no compiler version to match up.
+- `sveld` bundles its own template parser to parse `.svelte` files, kept in parity with `svelte/compiler` (see [Approach](#approach)). Parsing does not depend on the Svelte version installed in your project, so Svelte 3 and Svelte 4 codebases parse the same way Svelte 5 codebases do — there is no compiler version to match up.
+- [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes) and [`checkExamples`](#compile-checked-example-blocks-checkexamples) are optional and need `typescript` 7 or later (which provides `typescript/unstable/async`) plus a `tsconfig.json`. Everything else, including `.d.ts` generation, is AST-only and never loads TypeScript. If either is enabled and TypeScript can't be started (missing, too old, or no `tsconfig.json`), the run fails loudly: `sveld()` throws and the CLI exits `2` naming the requirement, rather than silently skipping the check.
 
 ## Usage
 
@@ -434,6 +545,15 @@ export default defineConfig({
 
 Since Vite uses Rollup for production builds, the same plugin works in Rollup configs.
 
+Unlike the CLI and the programmatic `sveld()` API, the plugin ignores `sveld.config.*` by default: pass `config: true` to load it and merge it with the options given here (these take precedence over the same key in the file), or a string to point at a specific config file.
+
+```ts
+sveld({
+  config: true,
+  json: true, // wins over `json` set in sveld.config.*
+});
+```
+
 By default, `sveld` uses the `"svelte"` field from your `package.json` to determine the entry point. You can override this by specifying an explicit `entry` option:
 
 ```js
@@ -472,7 +592,7 @@ npx sveld --json --markdown
 
 If no entry point can be resolved (no `package.json#svelte` field and no `--entry`), the CLI exits `1` and prints the reason to `stderr`. If `src/index.js` happens to exist relative to your working directory, sveld falls back to it and prints a one-line note asking you to set `package.json#svelte` (or `--entry`) instead of relying on the fallback.
 
-Flags are kebab-case: `--entry`, `--glob`, `--types`, `--json`, `--markdown`, `--fail-fast`, `--dry-run`, `--cache`, `--resolve-types`, `--check-examples`, `--report-diagnostics`, `--strict`, `--check`, `--types-format`, `--quiet`, `--stdout`, `--format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. `--entry`, `--cache`, `--check`, and `--types-format` take their value either as `--flag=value` or as a separate `--flag value` argument (`sveld --entry src/index.js` and `sveld --entry=src/index.js` are equivalent); if the next argument starts with `--` it's not consumed as a value, so `--cache` and `--check` fall back to their default location and `--entry` and `--types-format` report a usage error naming the flag. Boolean flags (`--json`, `--glob`, `--strict`, and the like) never consume a following argument. An unrecognized flag (e.g. `--markdwon`) prints `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Unknown flag: --markdwon Did you mean --markdown?`. sveld takes no positional arguments, so any non-flag argument errors the same way.
+Flags are kebab-case: `--entry`, `--glob`, `--types`, `--json`, `--markdown`, `--custom-elements`, `--llms`, `--fail-fast`, `--dry-run`, `--cache`, `--resolve-types`, `--check-examples`, `--report-diagnostics`, `--strict`, `--check`, `--check-level`, `--types-format`, `--quiet`, `--stdout`, `--format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. `--entry`, `--cache`, `--check`, and `--types-format` take their value either as `--flag=value` or as a separate `--flag value` argument (`sveld --entry src/index.js` and `sveld --entry=src/index.js` are equivalent); if the next argument starts with `--` it's not consumed as a value, so `--cache` and `--check` fall back to their default location and `--entry` and `--types-format` report a usage error naming the flag. Boolean flags (`--json`, `--glob`, `--strict`, and the like) never consume a following argument. An unrecognized flag (e.g. `--markdwon`) prints `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Unknown flag: --markdwon Did you mean --markdown?`. sveld takes no positional arguments, so any non-flag argument errors the same way.
 
 Writer progress lines (`created "..."` / `unchanged "..."`) print to `stderr`, keeping `stdout` reserved for machine-readable data. Pass `--quiet` (or `quiet: true` in `sveld.config.*`) to suppress them; it does not suppress error messages, the diagnostics summary (`--report-diagnostics` / `--strict`), or the `--check` report.
 
@@ -482,16 +602,24 @@ Pass `--stdout` alongside exactly one of `--json`, `--markdown`, or `--custom-el
 
 `--stdout=ndjson` (only valid with `--json`) prints one minified JSON object per exported component per line instead of the single combined document, in the same order as the combined document's `components` array, e.g. `sveld --json --stdout=ndjson | jq -c 'select(.props | length > 0)'`. Lines are only written after the run completes (component records are only final after cross-component resolution), so this is a line-oriented serialization format, not incremental streaming. Bare `--stdout` (or `--stdout=json`) keeps the single-document behavior; any other value is a usage error.
 
-`--format=json` switches the `--check` report and the `--report-diagnostics` / `--strict` diagnostics summary from prose to JSON, so scripts and agents don't have to regex the text output, e.g. `sveld --json --check --format=json | jq '.bump'`. Channels are unchanged: the check report prints to `stdout` and the diagnostics summary to `stderr`, same as the text format. The default remains `--format=text`; an unrecognized value (e.g. `--format=yaml`) is a usage error that prints to `stderr` and exits `1` without generating anything.
+`--format=json` switches the `--check` report and the `--report-diagnostics` / `--strict` diagnostics summary from prose to JSON, so scripts and agents don't have to regex the text output, e.g. `sveld --json --check --format=json | jq '.bump'`. Channels are unchanged: the check report prints to `stdout` and the diagnostics summary to `stderr`, same as the text format. Each envelope (`{ kind: "check-report", schemaVersion: 1, ... }` / `{ kind: "diagnostics", schemaVersion: 1, diagnostics: [...] }`) carries its own `schemaVersion`, bumped independently of `COMPONENT_API.json`'s if either shape ever changes incompatibly. The default remains `--format=text`; an unrecognized value (e.g. `--format=yaml`) is a usage error that prints to `stderr` and exits `1` without generating anything.
+
+`--format=github` prints [GitHub Actions workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) instead: `::warning`/`::error` for each diagnostic (by `severity`) and `::error` for each `--check` change that meets `--check-level` (`major` by default), annotating the offending line directly in the PR's "Files changed" tab. Ignored diagnostics and changes below `--check-level` produce no annotation. When the `GITHUB_STEP_SUMMARY` env var is set (GitHub Actions sets it automatically), sveld also appends a Markdown table mirroring the same rows to that file, so the job summary shows them even for someone not reviewing the diff. A minimal workflow step:
+
+```yaml
+- run: npx sveld --json --check --report-diagnostics --strict=errors --format=github
+```
 
 Run `npx sveld --help` for the full flag list with descriptions, or `npx sveld --version` to print the installed version.
 
+Pass `--glob` with a directory as `--entry` (no barrel file) to document every `.svelte` file under it directly, with no re-export needed: each component's sanitized filename becomes its module name in JSON, Markdown, and the generated `index.d.ts`, in addition to the per-component `.d.ts` every `--glob` run already produces. This is the same set `mergeGlobbedComponents` discovers when `--glob` is combined with a file entry; a directory entry just has no barrel to layer it onto.
+
 ### Exit codes
 
 | Code | Meaning |
 |------|---------|
 | `0` | Success |
-| `1` | Usage or configuration error (unknown flag, bad flag value, unresolvable entry) |
+| `1` | Usage or configuration error (unknown flag, bad flag value, unresolvable entry, unresolved re-export or path alias) |
 | `2` | Generation failure (a component failed to parse under `--fail-fast`, or an unrecoverable pipeline error) |
 | `3` | Breaking API change detected by `--check` |
 | `4` | Diagnostics present under `--strict` |
@@ -518,16 +646,68 @@ Suggested semver bump: major.
     [BREAKING] prop "href" removed
 ```
 
-Removed props, events, or slots, and props that become required, are breaking (`major`). New optional props, new events, and widened union types are additive (`minor`). Changes to generics, `@restProps`, `@extends`, or context shapes are not classified further. If any of those changed, `--check` calls it breaking.
+| Change | Bump |
+| --- | --- |
+| Component added | `minor` |
+| Component removed | `major` |
+| Prop/export added (optional) | `minor` |
+| Prop/export added (required) | `major` |
+| Prop/export removed | `major` |
+| Prop/export became required | `major` |
+| Prop/export became optional | `minor` |
+| Prop/export type widened (union gained a member) | `minor` |
+| Prop/export type narrowed (union lost a member) | `major` |
+| Prop/export type changed (anything else) | `major` |
+| Function-typed prop/export gained a trailing optional param | `minor` |
+| Function-typed prop/export lost a param, or return type changed | `major` |
+| Prop gained a writable binding (`bind:`-able) | `minor` |
+| Prop lost a writable binding | `major` |
+| Prop/export default value changed (type unchanged) | `patch` |
+| `@deprecated` added | `minor` |
+| `@deprecated` removed | `patch` |
+| `constant`/`reactive` flag flipped | `minor` |
+| Event/slot added | `minor` |
+| Event/slot removed | `major` |
+| Event detail / slot props type widened | `minor` |
+| Event detail / slot props type narrowed or otherwise changed | `major` |
+| `generics`, `@restProps`, `@extends`, or context shape changed | `major` (not classified further) |
+| Description-only change | not reported |
 
 `--check` does not write the snapshot. Run `sveld --json` (or `sveld --json --check`) and commit the file when you want to update it. If there is no snapshot yet, `--check` prints a notice and exits `0`.
 
 Use `--check=<path>` to diff against a snapshot at a custom location (defaults to `jsonOptions.outFile`, or `COMPONENT_API.json`).
 
+By default `--check` only fails the run (exit `3`) on a `major` bump; `minor` and `patch` changes are still reported but don't fail CI. Pass `--check-level=minor` or `--check-level=patch` to fail the run at a lower threshold, e.g. to gate a package that promises no additive changes without a minor release.
+
+If the committed snapshot's `schemaVersion` doesn't match the version `sveld` currently emits, `--check` reports a `kind: "schema"` entry instead of diffing (a version mismatch isn't a semver bump) and exits `1` (usage error): regenerate the snapshot with `sveld --json`.
+
 The CLI exits non-zero on any fatal error (an unreadable entry, a config file that throws, etc.), not just on `--strict`/`--check` findings, so it's safe to use either flag as a CI gate. See [Exit codes](#exit-codes) for how these are differentiated.
 
 Pass `--format=json` for a machine-readable report on `stdout` instead of the prose above, e.g. `sveld --check --format=json | jq '.bump'` or `sveld --check --format=json | jq '.changes[] | select(.bump == "major")'`.
 
+### CI: strictness profiles (`--strict=ci`/`--strict=local`)
+
+CI and local runs usually want a different bundle of `strict`, `reportDiagnostics`, `check`, and `checkExamples` flags, previously assembled by hand. `--strict=ci`/`strict: "ci"` and `--strict=local`/`strict: "local"` are shorthands for two common bundles. Bare `--strict`/`strict: true` (and `--strict=errors`) are unchanged.
+
+`--strict=ci` expands to `{ strict: true, reportDiagnostics: true, check: true, checkExamples: true }` — the full gate for a CI job:
+
+```sh
+npx sveld --json --strict=ci
+```
+
+`--strict=local` expands to `{ reportDiagnostics: true }` — diagnostics printed for a developer to see, without failing the command or requiring a committed `COMPONENT_API.json` snapshot:
+
+```sh
+npx sveld --json --strict=local
+```
+
+The profile's keys are applied first, then any other key set alongside `strict` overrides it, so you can opt back out of one piece:
+
+```ts
+// Everything --strict=ci implies, except the TypeScript-checked half of checkExamples.
+await sveld({ json: true, strict: "ci", checkExamples: "syntax" });
+```
+
 ### Node.js
 
 You can also call `sveld` from Node.js. See [Requirements](#requirements) for supported Node versions and the ESM-only constraint.
@@ -560,19 +740,20 @@ const { diagnostics } = await sveld({
 });
 ```
 
-`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)).
+`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)). `errors` is always populated too: components that failed to parse, whether or not `failFast` is set.
 
-Pass `check: true` (or `check: "<path>"` for a custom snapshot location) to diff against a committed `COMPONENT_API.json`, the same way `--check` does on the CLI. The result lands on `SveldResult.check`; sveld does not print it or touch `process.exitCode` for you, so inspect and act on it yourself:
+Pass `check: true` (or `check: "<path>"` for a custom snapshot location) to diff against a committed `COMPONENT_API.json`, the same way `--check` does on the CLI. The result lands on `SveldResult.check`. `sveld()` never touches `process.exitCode` itself; it returns a suggested `exitCode` (`0`, `3` for a breaking `check` result, or `4` for `strict` diagnostics — the same mapping the CLI uses, `3` winning over `4`) so you can assign it yourself:
 
 ```js
 import { formatCheckReport } from "sveld";
 
-const { check } = await sveld({ json: true, check: true });
+const { check, exitCode } = await sveld({ json: true, check: true });
 
 if (check) {
   console.log(formatCheckReport(check));
-  if (check.bump === "major") process.exitCode = 1;
 }
+
+process.exitCode = exitCode;
 ```
 
 See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check) for how changes are classified.
@@ -594,6 +775,23 @@ sveld({
 });
 ```
 
+#### `jsonOptions.source`
+
+Every prop, slot, event, typedef, and context in `COMPONENT_API.json` carries a `source` position range (plus `componentCommentSource` on the component itself) when the parser has a stable AST position for it. For a large component library this is a substantial share of the file — roughly a quarter of `COMPONENT_API.json` for a 150+ component library — and many consumers (docs sites, LLM context) never read it.
+
+Set `jsonOptions.source` to `false` to omit every `source`/`componentCommentSource` range and shrink the file:
+
+```js
+sveld({
+  json: true,
+  jsonOptions: {
+    source: false,
+  },
+});
+```
+
+`source: true` is the default; every other field is unaffected. `EntryExport.source` (the declaring module's relative path, from `documentExports`) is a different field with a string value and is never stripped.
+
 ### Browser
 
 `sveld/browser` is a Node-free subpath export for running `sveld` client-side — e.g. an in-browser Svelte playground or REPL that parses whatever `.svelte` source the user typed and renders docs for it live. It bundles with Vite, esbuild, webpack, or Rollup without a `node:fs`/`node:path` polyfill.
@@ -637,11 +835,11 @@ const cem = buildCustomElementsManifest(components, {
 
 `ComponentParser` is stateful but reusable across parses — call `parseSvelteComponent` again on the same instance for the next component instead of constructing a new one each time.
 
-See [`playground/`](playground) in this repo for a working example: it parses Svelte source typed into an editor and renders JSON, Markdown, TypeScript, and Custom Elements Manifest tabs, all client-side.
+See [`playground/`](playground) in this repo for a working example: it parses Svelte source typed into an editor and renders JSON, Markdown, TypeScript, and Custom Elements Manifest tabs, all client-side. Deployed at [sveld.onrender.com](https://sveld.onrender.com).
 
 ### Config File
 
-Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API.
+Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API. The Vite/Rollup plugin ignores it unless you opt in with the [`config`](#vite) option.
 
 Import `defineConfig` from `sveld` for typed options. Config files must use ESM syntax (`export default`).
 
@@ -673,6 +871,19 @@ export default {
 };
 ```
 
+Merging is one level deep for object-valued options (`typesOptions`, `jsonOptions`, `markdownOptions`, `customElementsOptions`, `additionalWriters`): setting one nested key at the CLI or in `sveld()` doesn't drop sibling keys set in the config file. Arrays and functions (e.g. `markdownOptions.onAppend`) are replaced outright, never merged.
+
+```js
+// sveld.config.js
+export default {
+  typesOptions: { outDir: "dist", preamble: "// license" },
+};
+```
+
+`npx sveld --types-format=component` keeps `outDir` and `preamble` from the file and adds `format: "component"`, rather than replacing `typesOptions` entirely.
+
+An unrecognized option key (top-level, or inside a `*Options` object) is not an error: it prints a `console.warn` naming the key, with a "did you mean" suggestion when a known key is close enough.
+
 A bad config (syntax error, throws at load time, or no default-export object) fails with an error that names the file.
 
 ### Publishing to NPM
@@ -708,22 +919,41 @@ The `svelte` condition lets bundlers that understand it (Vite, Rollup, webpack v
 - **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
 - **`documentExports`** (boolean, optional): Include consts, functions, and types from the entry barrel in JSON (`exports`) and Markdown ("Exports"). Off by default. See [Documenting Entry Exports](#documenting-entry-exports).
 - **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
-- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `format`.
+- **`typesOptions`** (object, optional): Options for TypeScript definition generation.
+  - **`outDir`** (string, optional, default: `"types"`): Output directory for generated `.d.ts` files, relative to the project root.
+  - **`preamble`** (string, optional, default: `""`): Raw text prepended to the top of the generated `index.d.ts` barrel file, before the `export * from "./..."` lines. Useful for license headers or lint-disable comments. See [`typesOptions.preamble`](#typesoptionspreamble) below.
   - **`format`** (`"class"` | `"component"`, optional, default: `"class"`): `.d.ts` output shape. `"class"` extends `SvelteComponentTyped`; `"component"` emits the Svelte 5 `Component` type. Also available as `--types-format`. See [`.d.ts` output format](#dts-output-format-typesoptionsformat).
 - **`json`** (boolean, optional): Generate component documentation in JSON format.
 - **`jsonOptions`** (object, optional): Options for JSON output.
+  - **`outFile`** (string, optional, default: `"COMPONENT_API.json"`): Path (relative to the project root) for the single combined JSON document. Ignored when `outDir` is set.
+  - **`outDir`** (string, optional): Emit one JSON file per component (`<ComponentName>.api.json`) into this directory instead of a single combined file. See [`jsonOptions.outDir`](#jsonoptionsoutdir).
+  - **`source`** (boolean, optional, default: `true`): Set to `false` to omit every `source`/`componentCommentSource` position range from the output. See [`jsonOptions.source`](#jsonoptionssource).
 - **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
 - **`markdownOptions`** (object, optional): Options for Markdown output.
+  - **`outFile`** (string, optional, default: `"COMPONENT_INDEX.md"`): Path (relative to the project root) for the single combined Markdown document. Ignored when `outDir` is set.
+  - **`outDir`** (string, optional): Emit one `<ModuleName>.md` file per component into this directory, plus an index `README.md` linking to each, instead of a single combined file. See [`markdownOptions.outDir`](#markdownoptionsoutdir).
+  - **`write`** (boolean, optional, default: `true`): Set to `false` to skip writing to disk — the rendered combined document is still returned, or (with `outDir` set) no files are written at all.
+  - **`onAppend`** (function, optional): Callback invoked every time a heading, quote, paragraph, divider, or raw block is appended to the document. Lets you inject extra content, e.g. a summary line under the title. See [`markdownOptions.onAppend`](#markdownoptionsonappend) below.
 - **`customElements`** (boolean, optional): Generate a [Custom Elements Manifest](#custom-elements-manifest) (`custom-elements.json`). Also available as the `--custom-elements` CLI flag.
-- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output, including `outFile`.
-- **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when `.svelte` source changes during `vite dev` / `vite build --watch`. Only the changed component and the components that depend on it via [`@extendProps`](#extendprops) / `@extends` are re-parsed, rather than rebuilding every component. Without this option, the plugin only runs during `vite build`.
+- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output.
+  - **`outFile`** (string, optional, default: `"custom-elements.json"`): Path (relative to the project root) for the generated manifest file.
+- **`llms`** (boolean, optional): Generate an [`llms.txt` / `llms-full.txt`](#llmstxt-output) pair. Also available as the `--llms` CLI flag.
+- **`llmsOptions`** (object, optional): Options for `llms.txt` / `llms-full.txt` output.
+  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
+  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`.
+  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
+  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title.
+- **`config`** (boolean | string, optional, default: `false`): Load `sveld.config.{js,mjs,ts}` and merge it with these options; these options win when a key is set in both. `true` resolves the config from the Vite project root (or `process.cwd()` outside Vite); a string is an explicit path to the config file. See [Config File](#config-file).
+- **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when relevant source changes during `vite dev` / `vite build --watch`. A reparse is triggered by: editing a component; editing the entry barrel itself, which adds/removes the corresponding component; or editing a non-`.svelte` file a component depends on via [`@extendProps`](#extendprops) / `@extends` or a typedef `import("./x")` reference. Only the affected components are re-parsed, rather than rebuilding every component. Overlapping regenerations are queued, never run concurrently. Without this option, the plugin only runs during `vite build`.
 - **`failFast`** (boolean, optional, default: `false`): Abort the entire run when a single component fails to parse. By default, parse failures are collected as diagnostics (and reported to `stderr`) so the remaining components still emit their output. Also available as the `--fail-fast` CLI flag.
 - **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. Also available as `--resolve-types` (`--resolveTypes` remains as a deprecated alias). See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
 - **`cache`** (boolean | string, optional, default: `true`): Write parsed component output to disk and skip re-parsing unchanged files on later runs. On by default, writing to `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path; pass `false` to disable. Also available as `--cache` / `--cache=<path>` / `--cache=false`. See [Persistent parse cache](#persistent-parse-cache-cache).
-- **`checkExamples`** (boolean, optional, default: `false`): Run plain TS/JS `@example` blocks through the TypeScript program. Broken ones get an `example-compile-error` diagnostic. Also available as `--check-examples` (`--checkExamples` remains as a deprecated alias). See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
+- **`checkExamples`** (`boolean | "syntax"`, optional, default: `false`): `true` runs plain TS/JS `@example` blocks through the TypeScript program (`example-compile-error` diagnostics) and `svelte`/`html` blocks through sveld's own template parser (`example-syntax-error` diagnostics). `"syntax"` runs only the markup path, so `typescript` is never loaded. Also available as `--check-examples` / `--check-examples=syntax` (`--checkExamples` remains as a deprecated alias). See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
 - **`reportDiagnostics`** (boolean, optional, default: `false`): Print unresolved-type diagnostics to stderr (CLI) or `console.warn` (programmatic API). Also available as `--report-diagnostics`. See [Type inference diagnostics](#type-inference-diagnostics).
-- **`strict`** (boolean, optional, default: `false`): Exit with code `4` when diagnostics exist. Implies `reportDiagnostics`. Also available as `--strict`. See [Type inference diagnostics](#type-inference-diagnostics).
+- **`strict`** (`boolean | "errors" | "ci" | "local"`, optional, default: `false`): Exit with code `4` when diagnostics exist. Implies `reportDiagnostics`. `"errors"` fails only on `severity: "error"` diagnostics, letting `warning` ones through. `"ci"` and `"local"` are strictness profiles that expand into other options before this object's own keys are applied. Also available as `--strict` / `--strict=errors` / `--strict=ci` / `--strict=local`. See [Type inference diagnostics](#type-inference-diagnostics) and [CI: strictness profiles](#ci-strictness-profiles---strictci---strictlocal).
+- **`diagnostics.ignore`** (`Array<{ code?: string; component?: string; name?: string }>`, optional): Marks matching diagnostics `ignored` — they're still reported and counted, but never fail `strict`. `component` is a glob; an omitted field on a matcher matches anything. No CLI flag; config-file or `sveld()` only. See [Ignoring diagnostics](#ignoring-diagnostics).
 - **`check`** (boolean | string, optional, default: `false`): Diff the parsed component API against a committed snapshot and assign a semver bump to each change. `true` uses the `json` writer's `outFile` (or `COMPONENT_API.json`); a string sets a custom snapshot path. Also available as `--check` / `--check=<path>`. On the CLI this exits `3` on a breaking change; from `sveld()` it's returned on `SveldResult.check` for you to act on. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
+- **`checkLevel`** (`"major" | "minor" | "patch"`, optional, default: `"major"`): Minimum bump `--check` fails the CLI run on. Also available as `--check-level`. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
 - **`quiet`** (boolean, optional, default: `false`): Suppress writer progress logs (`created "..."` / `unchanged "..."`), which print to `stderr` by default. Does not suppress error messages, the diagnostics summary, or the `--check` report. Also available as `--quiet`.
 - **`dryRun`** (boolean, optional, default: `false`): Resolve the entry, load config, and parse components through the real pipeline, then print `would write "<path>"` to `stdout` for each output file instead of writing it, including the parse cache. Diagnostics, `strict`, and `check` behave as in a real run. CLI-only via `--dry-run`; the Vite plugin does not expose this option.
 
@@ -738,6 +968,74 @@ sveld({
 })
 ```
 
+#### `typesOptions.preamble`
+
+Use `typesOptions.preamble` to prepend raw text to the generated `types/index.d.ts` barrel file — for example, a license header that should ship with every published `.d.ts` file.
+
+```js
+sveld({
+  types: true,
+  typesOptions: {
+    preamble: "// Copyright (c) 2026 Acme Inc. All rights reserved.\n\n",
+  },
+});
+```
+
+```ts
+// types/index.d.ts
+// Copyright (c) 2026 Acme Inc. All rights reserved.
+
+export { default as Button } from "./Button.svelte";
+```
+
+`preamble` only affects the barrel file (`index.d.ts`); per-component `.d.ts` files are untouched.
+
+#### `markdownOptions.onAppend`
+
+`markdownOptions.onAppend` fires on every heading, quote, paragraph, divider, and raw block written to the Markdown document, and receives the block's `type`, the in-progress `WriterMarkdown` document, and the full component map. Use it to inject extra content, e.g. a summary line under the `h1` title.
+
+```js
+import pkg from "./package.json" with { type: "json" };
+
+sveld({
+  markdown: true,
+  markdownOptions: {
+    onAppend: (type, document, components) => {
+      if (type === "h1") {
+        document.append(
+          "quote",
+          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
+        );
+      }
+    },
+  },
+});
+```
+
+```md
+# Component Index
+
+> 1 components exported from sveld-scratch@1.0.0.
+```
+
+#### `markdownOptions.outDir`
+
+With `markdown: true`, `sveld` writes a single `COMPONENT_INDEX.md` at the project root, documenting every component.
+
+Use `markdownOptions.outDir` to split that into one `<ModuleName>.md` file per component, plus an index `README.md` that links to each one (and holds the Exports section when `documentExports` is on — per-component sections live entirely in their own file):
+
+```js
+sveld({
+  markdown: true,
+  markdownOptions: {
+    // e.g. "docs/Button.md", "docs/README.md"
+    outDir: "docs",
+  },
+});
+```
+
+`onAppend` still fires for both the index and every per-component file. `outFile` is ignored once `outDir` is set.
+
 ## Documenting Entry Exports
 
 Most entry barrels re-export more than `.svelte` components. Set `documentExports: true` to add consts, functions, and types to the JSON and Markdown output.
@@ -762,7 +1060,11 @@ export type { Theme } from "./types";
 
 From that barrel, `sveld` documents `VERSION`, `clamp`, and `Theme`. `Button` still goes through the component path. Type text is copied from source, not resolved with `tsc`, same as the rest of the tool.
 
-JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each item has `name`, `kind`, type text, optional JSDoc `description`, and `source`.
+Nested barrels are followed too: `export { X } from "./dir"`, where `./dir/index.js` itself re-exports `.svelte` files, resolves `X` to the underlying component without needing `--glob`.
+
+JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each item has `name`, `kind`, type text, optional JSDoc `description`, `source`, and — same as props — optional `@deprecated` and pass-through `tags`. A deprecated export's name is struck through in the Markdown table, same as a deprecated prop. See [`@deprecated`](#deprecated).
+
+An overloaded function (repeated `export function f(...)` signatures, or an import re-exported through a barrel) always documents the implementation signature, i.e. the last declaration. An `enum` export's `type` is the literal union of its members' values (`"A" | "B"` for a string enum, `0 | 1` for a numeric one), falling back to the bare enum name when a member's value can't be determined (e.g. a computed initializer). When two different modules export the same name (most commonly via `export * from "./a"; export * from "./b"`), `sveld` keeps whichever was declared first and prints a warning; it does not silently pick one or emit both.
 
 ## JSON Output
 
@@ -771,6 +1073,14 @@ component API. For stable output, generated `events` arrays are emitted in deter
 
 The JSON Schema lives on GitHub ([path to file](https://github.com/carbon-design-system/sveld/blob/main/schema/component-api.schema.json), [raw URL](https://raw.githubusercontent.com/carbon-design-system/sveld/main/schema/component-api.schema.json)). Use it to validate generated `COMPONENT_API.json` files. Optional fields may be missing when the parser has no stable source for that metadata.
 
+`sveld` also ships the schema as a package subpath, so you don't need network access to validate at build time:
+
+```ts
+import schema from "sveld/schema/component-api.schema.json" with { type: "json" };
+```
+
+`require.resolve("sveld/schema/component-api.schema.json")` works too. The `$id` in the schema still points at the `main` branch on GitHub for tooling that dereferences it by URL, but that URL always reflects the latest release; the copy packaged with your installed `sveld` version is the authoritative one for the output it produced.
+
 ```ts
 interface ComponentApiJson {
   schemaVersion: 1;
@@ -792,6 +1102,8 @@ interface EntryExport {
   type?: string;
   value?: string;
   description?: string;
+  deprecated?: string | true;
+  tags?: Array<{ name: string; body: string }>;
   source?: string;
   isTypeOnly: boolean;
 }
@@ -906,15 +1218,62 @@ sveld({
 
 Each exported component becomes one `javascript-module` with a class declaration:
 
-- **Members** — every prop becomes a `ClassField` (`name`, `type.text`, `default`, `description`, `deprecated`).
-- **Attributes** — derived conservatively from props: only props with a bare primitive type (`string`, `number`, or `boolean`) become attributes, using the same default name Svelte's custom-element runtime uses (`prop.toLowerCase()`, unless the tool's own `attribute` override applies). Props whose lowercased name collides with another prop are dropped from `attributes` on both sides, since which one wins at runtime is ambiguous. Complex types (arrays, objects, unions, custom types) never become attributes.
+- **Members** — every `export let`/`const` prop becomes a `ClassField` (`name`, `type.text`, `default`, `description`, `deprecated`; `readonly: true` for an `export const`). An accessor prop (`export function`) becomes a `ClassMethod` (`name`, `static: false`, `parameters`, `return.type.text`) instead — see [Accessor methods](#accessor-methods) below.
+- **Attributes** — every prop becomes an attribute (Svelte's custom-element runtime observes one for every prop by default), excluding `export function` accessors. The attribute name is `prop.toLowerCase()` by default, or the `customElement.props.<name>.attribute` config when set — see [Object-form `customElement` config](#object-form-customelement-config) below. Props that collide on the same attribute name keep the first (in declaration order); the rest are skipped with a console warning, since which one wins at runtime is ambiguous.
 - **Events** — dispatched events (`createEventDispatcher()`, and `$host().dispatchEvent(...)` from inside a custom element) become `{ name, type: { text: "CustomEvent<...>" } }`. Forwarded (`on:click`) events are left out, since they aren't dispatched by the component's own class.
 - **Slots** — named and default slots, with descriptions. The default slot's `name` is `""`, matching the CEM convention.
+- **`cssParts`/`cssProperties`** — from `@csspart`/`@cssprop` JSDoc tags — see [CSS parts and custom properties](#css-parts-and-custom-properties) below.
 
 When a component sets `<svelte:options customElement="x-foo" />` (or the object form, `<svelte:options customElement={{ tag: "x-foo" }} />`), its declaration gets `tagName: "x-foo"` and `customElement: true`, and the module's `exports` include a `custom-element-definition` export alongside the plain `js` export.
 
 Components without `customElement` still emit a plain class declaration (no `tagName`/`customElement`) — useful for documenting the class shape even before it's compiled as a custom element, but the manifest is most useful for `customElement`-compiled builds, where downstream tooling can resolve `tagName`, `attributes`, and `events` for actual custom-element usage.
 
+### Object-form `customElement` config
+
+The object form of `<svelte:options customElement={{ ... }} />` is read in full, not just `tag`:
+
+```svelte
+<svelte:options
+  customElement={{
+    tag: "x-widget",
+    shadow: "none",
+    props: {
+      variant: { attribute: "data-variant" },
+      active: { reflect: true },
+      tags: { type: "Array" }
+    },
+    extend: (customElementConstructor) => customElementConstructor
+  }}
+/>
+```
+
+| Config | Effect on the manifest |
+| --- | --- |
+| `props.<name>.attribute` | Overrides that prop's attribute name (default: `name.toLowerCase()`). `attribute: false` omits the prop's attribute entirely. |
+| `props.<name>.reflect` | Adds `reflects: true` to that prop's attribute. |
+| `props.<name>.type` | `"Array"`/`"Object"` appends a note to the attribute's description that the value is JSON-serialized (matching Svelte's runtime `JSON.stringify`/`JSON.parse` for those types); the attribute's `type.text` is still the prop's own TS type, not this config value. |
+| `shadow`, `extend` | Parsed and available on the raw `ParsedComponent.customElement` (Node API), but don't affect the manifest. |
+
+This full config (`tag`, `shadow`, `props`, `extend`) is also on `ParsedComponent.customElement` in the JSON output (`COMPONENT_API.json`), alongside the existing `customElementTag` shorthand.
+
+### Accessor methods
+
+An `export function` prop (a Svelte accessor, e.g. `export function focus() { ... }`) becomes a `ClassMethod`, not a `ClassField`, and is excluded from `attributes` (accessors aren't part of Svelte's props definition). `parameters`/`return` come from `@param`/`@returns` JSDoc when present, otherwise from splitting the function's TypeScript signature text (e.g. `(id: string) => boolean`).
+
+### CSS parts and custom properties
+
+Document shadow-DOM styling hooks with `@csspart`/`@cssprop` (alias `@cssproperty`) tags in the component's own JSDoc comment (the same comment block `@slot` tags go in):
+
+```js
+/**
+ * @csspart header - Styles the header region.
+ * @cssprop {Color} [--card-background=white] - Background color of the card.
+ * @cssprop --card-border-color - Border color of the card.
+ */
+```
+
+`@cssprop`'s `{type}` and `[--name=default]` are both optional, following the [Custom Elements Manifest analyzer](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#css-custom-properties) grammar. These populate `cssParts`/`cssProperties` on the class declaration, and `ParsedComponent.cssParts`/`cssProperties` in the JSON output; the Markdown writer renders them as two extra tables when present.
+
 ### Consuming the manifest
 
 Most tools discover `custom-elements.json` through a `customElements` field in `package.json`, pointing at the generated file:
@@ -931,6 +1290,196 @@ With that in place:
 - [Storybook](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#extracting-argtypes) for web components reads the manifest to auto-generate `argTypes` (controls, docs tables) for `customElement`-compiled components, once you point it at the file (e.g. `setCustomElementsManifest` from `@storybook/web-components`, or `customElements: "custom-elements.json"` in `.storybook/main.js`).
 - Any other tool built against the [Custom Elements Manifest spec](https://github.com/webcomponents/custom-elements-manifest) (API viewers, doc generators, linters) can read the file directly without sveld-specific integration.
 
+## llms.txt Output
+
+Set `llms: true` to emit an [`llms.txt`](https://llmstxt.org) / `llms-full.txt` pair: `llms.txt` is an index of every exported component (one link plus a one-line summary each), and `llms-full.txt` is the flattened full reference (every component's Props, Bindings, Events, Slots/Snippets, Typedefs, and Module exports, as terse Markdown tables). Props and Events Description columns include `@since`/`@example` tags, same as `COMPONENT_INDEX.md`.
+
+```diff
+sveld({
++  llms: true,
+})
+```
+
+- **`llms`** (boolean, optional): Generate `llms.txt` and `llms-full.txt`. Also available as the `--llms` CLI flag.
+- **`llmsOptions`** (object, optional):
+  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
+  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`, e.g. `[Button](<linkBase>/Button)`. Set this to your published docs site's base path.
+  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
+  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title. Omitted when neither is set.
+
+Each component's one-line summary in `llms.txt` is the first sentence of its [`@component` comment](#component-comments), falling back to `"Component"`. Set `documentExports: true` to also list entry-barrel exports (consts, functions, types) in `llms.txt` under an `## Exports` heading.
+
+## Custom Writers
+
+`json`, `markdown`, `types`, and `custom-elements` are all built on the same
+extensibility point: a small writer registry that third parties can use to
+add new output formats without a core PR. This is a stable, public part of
+sveld's API — the four built-in writers register through it in
+`src/writer/built-in-writers.ts`, there is no separate "internal" path.
+
+### The `OutputWriter` contract
+
+```ts
+interface OutputWriter<TOptions = unknown> {
+  name: string;
+  /** Which component set this writer expects. @default "exported" */
+  componentSet?: "exported" | "all";
+  write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
+}
+```
+
+- **`name`** is how the plugin's `additionalWriters` option (and anything else
+  that calls `getWriter`) looks the writer up. Pick something that won't
+  collide with `types` / `json` / `markdown` / `custom-elements` or another
+  third-party writer.
+- **`componentSet`** picks which map `write` receives:
+  - `"exported"` (the default) — components reachable from the entry barrel,
+    keyed by `moduleName`. This is what `json` / `markdown` /
+    `custom-elements` use.
+  - `"all"` — every `--glob`-discovered `.svelte` file, keyed by resolved
+    `filePath` instead of `moduleName` (two files in different directories
+    can share a basename). This is what `types` uses.
+- **`write`** receives a `ComponentDocs` (`Map<string, ComponentDocApi>`) —
+  the same `ComponentDocApi` shape documented in [JSON Output](#json-output).
+  Don't iterate the raw map yourself; call `buildComponentApiDocument(components, { entryExports })`
+  (also exported from `sveld`) to get the sorted, `diagnostics`-stripped,
+  schema-versioned document the built-in writers build from. It's memoized
+  per `components` map, so calling it more than once in one run is free.
+- **`options`** always carries `dryRun` alongside whatever fields the writer
+  itself defines. See [The `dryRun` contract](#the-dryrun-contract) below.
+
+### Registering a writer
+
+```ts
+import { registerWriter } from "sveld";
+
+registerWriter({
+  name: "my-format",
+  write(components, options) {
+    // ...
+  },
+});
+```
+
+`registerWriter` is a side effect — call it once, before the plugin or CLI
+runs, e.g. at the top of `vite.config.ts` or `sveld.config.ts`, or in a file
+either of those imports.
+
+Registering a `name` that's already taken — a built-in writer's name, or
+another `registerWriter` call — throws instead of silently overwriting it.
+Pass `{ replace: true }` as a second argument when overwriting is intentional
+(e.g. re-registering a writer module during development):
+
+```ts
+registerWriter(
+  {
+    name: "my-format",
+    write(components, options) {
+      // ...
+    },
+  },
+  { replace: true },
+);
+```
+
+### The `dryRun` contract
+
+Every writer — built-in or `additionalWriters` — receives `dryRun: true` in
+its `options` when the run is `sveld --dry-run` (or `{ dryRun: true }` from
+the programmatic API). A writer must check it and skip touching disk; sveld
+does not do this for you:
+
+```ts
+import { writeFileSync } from "node:fs";
+
+registerWriter({
+  name: "my-format",
+  write(components, options: { outFile: string; dryRun?: boolean }) {
+    if (options.dryRun) {
+      console.log(`would write "${options.outFile}"`);
+      return;
+    }
+    writeFileSync(options.outFile, "...");
+  },
+});
+```
+
+A writer that throws — synchronously or from a rejected promise — has its
+error re-thrown as `sveld: writer "<name>" failed: <message>`, with the
+original error attached as `cause`, so a broken third-party writer never
+fails silently or without saying which one.
+
+### Running it via the plugin
+
+```ts
+// vite.config.ts
+import sveld from "sveld";
+import "./writers/my-format"; // calls registerWriter as a side effect
+
+export default {
+  plugins: [
+    sveld({
+      additionalWriters: {
+        "my-format": { outFile: "MY_FORMAT.txt" },
+      },
+    }),
+  ],
+};
+```
+
+`additionalWriters` is keyed by the writer's registered `name`; the value is
+whatever options object that writer's `write` expects. An unknown name logs a
+warning and is skipped rather than failing the build. Registered writers run
+alongside whichever built-in outputs (`types` / `json` / `markdown` /
+`customElements`) are also enabled, and the same option is available from the
+programmatic Node API and from `sveld.config.ts` (`additionalWriters` lives on
+the options shared by all three entry points).
+
+### Worked example: a `components.txt` name-list writer
+
+Looking for an `llms.txt` writer specifically? Sveld ships one — see [llms.txt Output](#llmstxt-output). This example is a much smaller custom writer, just to show the pattern: a plain-text list of exported component names, needing nothing beyond `ComponentApiDocument`.
+
+```ts
+// writers/components-txt-writer.ts
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildComponentApiDocument, registerWriter } from "sveld";
+
+interface ComponentsTxtWriterOptions {
+  outFile?: string;
+}
+
+registerWriter<ComponentsTxtWriterOptions>({
+  name: "components-txt",
+  componentSet: "exported",
+  write(components, options = {}) {
+    const document = buildComponentApiDocument(components);
+    const rendered = document.components.map((component) => component.moduleName).join("\n");
+
+    writeFileSync(join(process.cwd(), options.outFile ?? "components.txt"), rendered);
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import sveld from "sveld";
+import "./writers/components-txt-writer";
+
+export default {
+  plugins: [
+    sveld({
+      additionalWriters: {
+        "components-txt": { outFile: "components.txt" },
+      },
+    }),
+  ],
+};
+```
+
+Running a build now produces a `components.txt` alongside the usual output,
+listing one exported component name per line.
+
 ## API Reference
 
 ### `reactive`
@@ -1299,7 +1848,7 @@ The `@typedef` tag defines a shared type used multiple times in a component. All
 
 #### Using `@property` for complex typedefs
 
-For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE.
+For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE. See the [`@property`](#property) reference for the tag's valid contexts.
 
 **Signature:**
 
@@ -1696,6 +2245,35 @@ function render(value: unknown, props: ComponentProps) {
 }
 ```
 
+### `@property`
+
+`@property` documents one field of an object. `sveld` only reads it in two places: directly inside a `@typedef {object}` block, and directly inside an `@event` block (after an explicit `@type {object}`, or with no `@type` at all — `sveld` builds the detail type from the collected `@property` entries). It has no effect anywhere else.
+
+**Valid contexts:**
+
+| Context | Behavior |
+| :- | :- |
+| After `@typedef {object} Name`, in the same comment block | Builds `Name`'s fields. See [Using `@property` for complex typedefs](#using-property-for-complex-typedefs). |
+| After `@event eventname`, in the same comment block | Builds the event's detail type. See [Using `@property` for complex event details](#using-property-for-complex-event-details). |
+| A plain prop with no `@typedef`/`@type {object}` | Not structured. Folded into the prop's description as literal text (`@property name - description`). |
+| Before a `@slot` / `@snippet` line | Dropped entirely — no structured output, and unlike other unrecognized tags in that position, it is not folded into the slot's description either. |
+| Inside `@callback` | Not read. Use `@param` for callback parameters instead. |
+
+**Signature:**
+
+```js
+/**
+ * @typedef {object} TypeName
+ * @property {Type} propertyName - Property description
+ *
+ * @event eventname
+ * @type {object}
+ * @property {Type} propertyName - Property description
+ */
+```
+
+Both forms support the same modifiers as typedef properties elsewhere in this doc: optional properties (`[name]`), default values (`[name=value]`), and nested/discriminated-union shapes. See the linked sections above for full signatures and worked examples with generated output.
+
 ### `@callback`
 
 The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.
@@ -1798,7 +2376,7 @@ Descriptions are optional for every slot, including the default slot. Put prose
  */
 ```
 
-Omit the `slot-name` to type the default slot.
+Omit the `slot-name` to type the default slot. `{Type}` itself is required; omitting it falls back to `Record<string, never>` and raises a [`sveld/slot-missing-type`](#diagnostic-codes) warning.
 
 ```js
 /**
@@ -2081,9 +2659,30 @@ export default class Component extends SvelteComponentTyped<
 > {}
 ```
 
+#### Detail inference without `@event`
+
+Without an `@event` tag or a typed dispatcher, `sveld` infers a dispatched event's detail type from the `dispatch()` call site itself:
+
+- A scalar literal argument narrows to its literal type: `dispatch("count", 5)` types the detail as `5`, not `number`. Use `@event` or a typed dispatcher (below) to widen it.
+- An object or array literal argument infers a structural type per field/element: `dispatch("save", { id })` types the detail as `{ id: string }` (resolving the `id` variable's own type), and `dispatch("items", [1, 2])` types it as `number[]`. Fields or elements sveld can't resolve fall back to `any` individually, not for the whole detail.
+
+#### Typed dispatchers
+
+`createEventDispatcher<T>()`'s generic argument (`lang="ts"`, or the JSDoc `/** @type {import('svelte').EventDispatcher<T>} */` cast form) works like an `@event` block for every member of `T`, including ones never actually dispatched in the file:
+
+```svelte
+<script lang="ts">
+  import { createEventDispatcher } from "svelte";
+
+  const dispatch = createEventDispatcher<{ save: { id: string }; cancel: null }>();
+</script>
+```
+
+`T` may also be a reference to a local `type`/`interface`. An `@event` tag for the same name still overrides the generic's detail type.
+
 #### Using `@property` for complex event details
 
-For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description.
+For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description. See the [`@property`](#property) reference for the tag's valid contexts.
 
 This is the idiomatic way to describe each field of an event detail. An inline object literal such as `@event {{ items: string[]; added: string[] }} change` types the payload but cannot carry per-field descriptions, since a nested block comment would terminate the host JSDoc. Declare the detail with `@type {object}` and `@property` instead to document every field.
 
@@ -2311,9 +2910,80 @@ export default class Component extends SvelteComponentTyped<
 
 Any free-text prose after the tags is attached to the event description, not to a property doc.
 
+### `@ignore` / `@internal`
+
+`@ignore` and `@internal` are equivalent aliases: either one excludes a prop, event, slot, typedef, module export, entry export, or context from every output — JSON, Markdown, `.d.ts`, and the Custom Elements Manifest. Use them for implementation details that would otherwise leak into the public API docs.
+
+The tag's position mirrors [`@deprecated`](#deprecated): before `@slot`/`@snippet`/`@typedef`/`@callback`, alongside the description, and after the `@event` line.
+
+```svelte
+<script>
+  /** The visible label. */
+  export let label = "";
+
+  /**
+   * Implementation detail; not part of the public API.
+   * @internal
+   */
+  export let debugId = "";
+
+  /**
+   * Fired when the value changes.
+   * @event {{ value: string }} change
+   */
+
+  /**
+   * Fired for internal diagnostics only.
+   * @event {{ reason: string }} debug
+   * @internal
+   */
+
+  /**
+   * @internal
+   * @slot {{}} debug-panel
+   */
+</script>
+```
+
+`debugId`, the `debug` event, and the `debug-panel` slot never appear in `COMPONENT_INDEX.md`, `COMPONENT_API.json`, the generated `.d.ts`, or the Custom Elements Manifest — as if they were never declared. Internally, the parser still records them (with an `internal: true` flag) on the raw parsed component; only `buildComponentApiDocument` — the shared step every writer runs through — filters them out, so a custom writer built on the raw parse result can still see them if it chooses to.
+
+For a context (`setContext(key, value)`), tag the JSDoc on the *value* variable, the same place its type annotation and description already live:
+
+```svelte
+<script>
+  /**
+   * @type {{ token: string }}
+   * @internal
+   */
+  let authContext = { token: "" };
+
+  setContext("auth", authContext);
+</script>
+```
+
+A whole inline object literal passed directly to `setContext` (no intermediate variable) has no JSDoc position of its own, so `@internal` isn't supported there. An individual property *inside* one can be marked `@internal`, though, as long as its value is an identifier carrying its own JSDoc:
+
+```svelte
+<script>
+  /**
+   * @type {string}
+   * @internal
+   */
+  let debugToken = "";
+
+  let publicUser = { name: "" };
+
+  setContext("session", { user: publicUser, debug: debugToken });
+</script>
+```
+
+Only the `debug` property is excluded from `session`'s generated shape; `user` and the context itself are unaffected.
+
+Because an internal member never appears in output, adding `@internal` to a previously-public prop, event, slot, or typedef is a breaking change for `--check` purposes (it disappears from the generated `.d.ts` just like an outright removal). Removing an already-`@internal` member, by contrast, is not breaking — it was never part of the committed public snapshot to begin with.
+
 ### `@deprecated`
 
-Add `@deprecated` to a prop, event, slot, or exported accessor. An optional message after the tag can explain why or name a replacement.
+Add `@deprecated` to a prop, event, slot, entry export, or exported accessor. An optional message after the tag can explain why or name a replacement.
 
 ```svelte
 <script>
@@ -2342,7 +3012,7 @@ Add `@deprecated` to a prop, event, slot, or exported accessor. An optional mess
 </script>
 ```
 
-For slots, put `@deprecated` before the `@slot` / `@snippet` line, alongside the description and any other [extra tags](#extra-jsdoc-tags-before-slot). For events, put it after the `@event` line.
+For slots, put `@deprecated` before the `@slot` / `@snippet` line, alongside the description and any other [extra tags](#extra-jsdoc-tags-before-slot). For events, put it after the `@event` line. For entry exports (see [Documenting Entry Exports](#documenting-entry-exports)), put it in the JSDoc directly above the `const`/`function`/`class`/`type`/`interface` declaration, same as a prop.
 
 Generated `.d.ts` files include an `@deprecated` JSDoc line so editors strike the symbol through. JSON adds a `deprecated` field (the message string, or `true` when the tag has no message). Markdown strikes through the name and adds a **Deprecated** badge with the message when present.
 
@@ -2358,6 +3028,184 @@ label?: string;
 { "name": "label", "deprecated": "Use the `text` prop instead." }
 ```
 
+### `@since`
+
+`@since` records the version a prop, event, or slot was introduced. `sveld` does not validate or parse the version text — whatever follows the tag is copied through as-is.
+
+**Valid contexts:**
+
+- **Prop / module export** — captured as a structured tag: JSON adds a `tags: [{ "name": "since", "body": "..." }]` array on the prop (kept separate from `description`), the generated `.d.ts` emits `@since ...` as its own JSDoc line above `@default`, and the Markdown table's Description column appends `@since ...` after the description, same as slots.
+- **`@event`** — same structured behavior as props, but only when `@since` is placed **after** the `@event` line in the same comment block (matching the [`@deprecated`](#deprecated) rule for events). Placed before `@event`, it is silently dropped.
+- **`@slot` / `@snippet`** — placed before the `@slot`/`@snippet` line, alongside the description. Fully surfaced in JSON, `.d.ts`, *and* the Markdown table. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported.** A `@since` before `@typedef` produces no output anywhere; it is silently dropped.
+- **`@component` comments** — passed through verbatim as part of the raw HTML comment text. See [@component comments](#component-comments).
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * A width prop.
+   * @since 1.2.0
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * A width prop.
+   * @since 1.2.0
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+Output (JSON, relevant slice):
+
+```json
+{ "name": "width", "description": "A width prop.", "tags": [{ "name": "since", "body": "1.2.0" }] }
+```
+
+Output (Markdown props table Description column):
+
+```
+A width prop.<br />@since 1.2.0
+```
+
+### `@see`
+
+`@see` adds a reference link or citation. Like `@since`, `sveld` does not resolve or validate the target — it is free text.
+
+**Valid contexts:**
+
+- **Prop / module export** — `@see` is *not* one of the small set of tags `sveld` structures specially, so it is folded verbatim into the prop's `description` as an extra line (`@see ...`) rather than getting its own `tags` entry. Because it lives in `description`, it *does* show up everywhere `description` is used: JSON, `.d.ts`, and the Markdown table.
+- **`@event`** — **not supported in either position** (before or after `@event`). A `@see` tag near an `@event` block is silently dropped in both JSON and `.d.ts`.
+- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`, alongside the description: fully supported in JSON, `.d.ts`, and Markdown, same as `@since`. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported.** Dropped silently, same as `@since`.
+- **`@component` comments** — passed through verbatim, same as `@since`.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * A width prop.
+   * @see https://example.com/width-docs
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * A width prop.
+   * @see https://example.com/width-docs
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+Output (Markdown props table Description column):
+
+```
+A width prop.<br />@see https://example.com/width-docs
+```
+
+### `@link`
+
+`{@link target}` (optionally `{@link target|display text}`) is an inline JSDoc tag used inside prose, not a block-level tag like the others on this page. `sveld`'s comment parser only treats a *line* as starting a new tag when it begins with `@` — `{@link ...}` always starts with `{`, so it's never intercepted. It is always literal text.
+
+**Valid contexts:** anywhere free-form description text is read — prop and module export descriptions, event descriptions, slot descriptions, entry export descriptions, typedef descriptions, `@component` HTML comments, and `@example` bodies. `sveld` never resolves or validates the target. JSON `description` and `.d.ts` JSDoc always keep the tag verbatim. **Markdown is the one exception:** in a prop, event, slot, or entry export's Description table cell, `{@link target|text}` / `{@link target}` is rewritten to a Markdown link, `[text](target)` / `[target](target)`. Typedef descriptions (rendered as a `.d.ts`-style code block) and `@component` comments keep the tag literal in Markdown too, since neither goes through the table-cell renderer.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * The element's width in pixels. See {@link https://example.com/width|width docs}.
+   * @type {number}
+   */
+  let { width = 0 } = $props();
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+export type ScratchProps = {
+  /**
+   * The element's width in pixels. See {@link https://example.com/width|width docs}.
+   * @default 0
+   */
+  width?: number;
+};
+```
+
+The same literal string appears unchanged in JSON `description`. The Markdown table's Description column instead shows: `The element's width in pixels. See [width docs](https://example.com/width).`
+
+### `@example`
+
+`@example` has two related uses: as a plain JSDoc tag whose body is copied into generated output, and — with `checkExamples: true` — as input to sveld's compile-checker for plain TS/JS example code. This section covers the tag itself; see [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples) for the type-checking feature.
+
+`@example` shares its underlying mechanism with `@since` (both are in the small set of tags `sveld` treats as structured "IDE passthrough" tags), so the valid contexts are the same:
+
+- **Prop / module export (including functions)** — structured `tags` entry in JSON, its own `@example` block in `.d.ts`, and appended to the Markdown table's Description column, same as `@since`.
+- **`@event`** — only when placed **after** the `@event` line in the same block, same rule as `@since`.
+- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`: fully supported in JSON, `.d.ts`, and Markdown. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
+- **`@typedef`** — **not supported**, dropped silently, same as `@since`.
+- **`@component` comments** — passed through verbatim; this is already how the [`@component` comments](#component-comments) example on this page uses `@example`.
+
+**Example:**
+
+```svelte
+<script>
+  /**
+   * Formats a value.
+   * @param {string} value
+   * @returns {string}
+   * @example
+   * ```js
+   * formatValue("ok");
+   * ```
+   */
+  export function formatValue(value) {
+    return value;
+  }
+</script>
+```
+
+Output (`.d.ts`):
+
+```ts
+/**
+ * Formats a value.
+ * @example
+ *  ```js
+ *  formatValue("ok");
+ *  ```
+ */
+formatValue: (value: string) => string;
+```
+
+`@param`/`@returns` are consumed into the function's type signature rather than kept as separate JSDoc lines.
+
+Output (Markdown props table Description column, newlines rendered as `<br />`):
+
+````
+Formats a value.<br />@example ```js<br /> formatValue("ok");<br /> ```
+````
+
 ### Context API
 
 `sveld` generates TypeScript definitions for Svelte's `setContext`/`getContext` by extracting types from JSDoc on context values.
@@ -3006,6 +3854,8 @@ export default class Component extends SvelteComponentTyped<
 
 When only `@param` tags are present without `@returns`, the return type defaults to `any`. When only `@returns` is present without `@param`, the function signature is `() => returnType`.
 
+The Markdown writer marks the same exports (a `const`, or a real function declaration) with Kind `accessor` in the Props table, instead of their raw `const`/`function` kind, matching the `.d.ts` output above.
+
 ## Troubleshooting
 
 **A prop came out `any`.** Enable [`reportDiagnostics`](#type-inference-diagnostics) (or `strict` to fail CI) to see which props sveld couldn't infer, then tighten them with `@type` or a native TypeScript annotation.
@@ -3014,6 +3864,10 @@ When only `@param` tags are present without `@returns`, the return type defaults
 
 **Output differs in CI.** Commit `COMPONENT_API.json` and run [`--check`](#ci-api-drift-checks---check) in CI so API drift fails the build instead of silently diverging.
 
+**`sveld: cannot resolve "..." from ...`.** An `export *` or a named re-export points at a module or path alias that doesn't resolve to a file on disk. Fix the specifier, or check the tsconfig/jsconfig `paths` entry it's supposed to match. This exits `1`; see [Exit codes](#exit-codes).
+
+**A path alias (`$lib`, `@components`, ...) isn't picked up.** sveld only reads aliases from `compilerOptions.paths` in the nearest `tsconfig.json` or `jsconfig.json`, found by walking up from the file doing the importing. Vite/SvelteKit alias config (`vite.config.*`, `svelte.config.*`) is not read directly — add the same aliases to `paths` so both tools agree. When a pattern has more than one mapping (`"$lib/*": ["./src/lib/*", "./lib/*"]`), sveld tries them in order and uses the first one that exists on disk, falling back to the first mapping if none do; among multiple matching patterns, the one with the longest non-wildcard prefix wins, regardless of declaration order (matching `tsc`).
+
 ## Contributing
 
 See [contributing guidelines](CONTRIBUTING.md).