# @pagesmith/core Full AI Reference

This file is the package-shipped source of truth for AI assistants using `@pagesmith/core`.

## Install

```bash
npm add @pagesmith/core
```

## Priority order

1. `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/setup-core.md` for bootstrap or retrofit work in existing apps and Vite repos.
2. `node_modules/@pagesmith/core/REFERENCE.md` for the complete API reference (content layer, collections, loaders, markdown, validation, assets, and `pagesmithContent`).
3. `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/usage.md` for package rules, integration contract, and copy-paste agent prompts.
4. `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/markdown-guidelines.md` for supported markdown, code-block, and authoring rules.
5. `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/migration.md` for upgrading an existing integration and adopting the latest package guidance.
6. `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/recipes.md` for step-by-step implementation patterns.

## Key rules

- Use `@pagesmith/core` for custom-site scenarios; do not force docs conventions from `@pagesmith/docs`.
- Prefer `defineCollection`, **`defineCollections`** (batch collection map), `defineConfig`, and `createContentLayer`.
- Prefer folder-based markdown entries when pages reference sibling assets.
- Keep content validation in collection schemas and validators, not scattered in app code.
- Treat the built-in Pagesmith renderer as the source for code-block UI; do not add separate copy-button scripts.

## Runtime requirements

- **Node.js 24+** (see `engines` in `@pagesmith/core` package.json).

## ContentLayerConfig

Fields: `collections`, optional `root`, `markdown`, `assets`, `plugins`, optional **`strict`** (fail fast on loader errors). There is no `cache` or `eager` field on `ContentLayerConfig`.

`markdown` (`MarkdownConfig`): `remarkPlugins`, `rehypePlugins`, `allowDangerousHtml` (default `true`), `math` (`boolean | 'auto'`, default `'auto'`), `shiki`, and `images`. `markdown.images` (`MarkdownImagesConfigSchema`): `lazyLoading` (default `true`) walks content images in document order, marking the first `eagerCount` (default `1`, the LCP hero) `fetchpriority="high"` and the rest `loading="lazy" decoding="async"`; set `lazyLoading: false` for no added loading attributes or `eagerCount: 0` to make every image lazy. Author-provided `loading`/`fetchpriority` are always respected.

## Concurrency utilities

Exported from the main `@pagesmith/core` entry: `defaultConcurrency()` returns `max(1, os.availableParallelism())`; `mapWithConcurrency(items, mapper, concurrency?)` runs an order-preserving bounded worker pool (defaults to `defaultConcurrency()`, clamps `< 1` to `1`, a thrown `mapper` rejects the batch like `Promise.all`). It is the single shared fan-out primitive used by content loading, image-variant emission, and `@pagesmith/site`'s route pre-rendering — prefer it over an unbounded `Promise.all(items.map(...))`.

## ContentLayer methods

| Method | Purpose |
|--------|---------|
| `getCollection(name)` | Load all entries in a collection |
| `getEntry(collection, slug)` | Single entry by slug |
| `convert(markdown, options?)` | Markdown to HTML outside collections |
| `invalidate` / `invalidateCollection` / `invalidateAll` | Cache invalidation |
| `validate(collection?)` | Run validators |
| `getCollectionNames()` | List configured collection names |
| `getCollectionDef(name)` | Lookup `CollectionDef` |
| `getCollections()` | All collection definitions |
| `invalidateWhere(collection, predicate)` | Invalidate matching entries |
| `watch(callback)` | FS watch on collection dirs |
| `getCacheStats()` | Cache size stats |

## CLI

The **`pagesmith`** CLI lives in **`@pagesmith/site`** (and is also published as **`pagesmith-site`**). `@pagesmith/core` does not ship that binary; `@pagesmith/docs` ships its own **`pagesmith-docs`** CLI for init, dev, build, preview, and MCP flows.

## Package files

All paths below are under `node_modules/@pagesmith/core/`:

| File | Purpose |
|---|---|
| `node_modules/@pagesmith/core/REFERENCE.md` | Complete API: content layer, collections, loaders, markdown pipeline, validation, assets, and `pagesmithContent` |
| `node_modules/@pagesmith/core/README.md` | User-facing quick start, direct rendering, Vite integration, and API overview |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/setup-core.md` | Canonical bootstrap/retrofit prompt for existing apps and Vite repos |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/core-guidelines.md` | Package-specific rules and responsibilities |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/markdown-guidelines.md` | Supported markdown, code-block, and authoring rules |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/usage.md` | Agent rules, integration shape, copy-paste prompts for common workflows |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/migration.md` | Upgrade playbook and copy-paste prompt for existing integrations |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/recipes.md` | Step-by-step recipes (collections, Vite, markdown, AI pointers) |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/errors.md` | Error catalog with patterns and fixes |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/changelog-notes.md` | Version highlights |
| `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/AGENTS.md.template` | Template for project AGENTS.md with task-specific file pointers |
| `node_modules/@pagesmith/core/llms.txt` | Compact AI context index (also exposed via `@pagesmith/core/llms`) |
| `node_modules/@pagesmith/core/llms-full.txt` | This file — full AI context (also exposed via `@pagesmith/core/llms-full`) |

## Agent prompts by use case

The `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/usage.md` file contains copy-paste prompts for these workflows:

1. **Bootstrap or retrofit in an existing app or Vite repo** → reads `node_modules/@pagesmith/core/REFERENCE.md`, `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/core-guidelines.md`, `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/recipes.md`
2. **Define content collections** → reads `node_modules/@pagesmith/core/REFERENCE.md`
3. **Write markdown content** (frontmatter, code blocks, diagram source fences such as mermaid) → reads `node_modules/@pagesmith/core/REFERENCE.md`
4. **Troubleshooting validation errors** → reads `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/errors.md`
5. **Upgrade existing integration** → reads `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/migration.md`, `node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/changelog-notes.md`, `node_modules/@pagesmith/core/REFERENCE.md`

## Pointer snippet for consuming projects

Add to project-level `CLAUDE.md` or `AGENTS.md`:

```
For @pagesmith/core usage and prompts, read node_modules/@pagesmith/core/skills/pagesmith-core-setup/references/usage.md
For the full @pagesmith/core API reference, see node_modules/@pagesmith/core/REFERENCE.md
```

## Related packages

- Site reference: `node_modules/@pagesmith/site/REFERENCE.md`
- Site usage: `node_modules/@pagesmith/site/skills/pagesmith-site-setup/references/usage.md`
- Site README: `node_modules/@pagesmith/site/README.md`
- Docs reference: `node_modules/@pagesmith/docs/REFERENCE.md`
- Docs usage: `node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/usage.md`
- Docs README: `node_modules/@pagesmith/docs/README.md`

## Validation

`ValidationIssue` includes an optional `source` field (`'schema' | 'content' | 'plugin' | 'custom'`) that identifies which validation phase produced the issue. Use this to categorize and prioritize fixes.

## MCP tools

The core MCP server (`@pagesmith/core/mcp`) exposes:

- `core_list_collections` — list all collections with loader type, directory, and schema fields
- `core_list_entries` — list entries in a collection (paginated, limit/offset)
- `core_get_entry` — load a single entry with rendered HTML, headings, and read time
- `core_validate` — run validation on one or all collections
- `core_search_entries` — search entries by title, description, tags, slug (case-insensitive, max 20)

Shared utilities exported from `@pagesmith/core/mcp`:
- `getPackageVersion(moduleDir)` — read version from package.json
- `resolvePackageDocPath(moduleDir, relativePath)` — resolve doc file path
- `asTextResource(uri, path)` — load file as MCP text resource

Version-matched MCP resources:
- `pagesmith://core/agents/usage`
- `pagesmith://core/llms-full`
- `pagesmith://core/reference`

## Related site package

Use `@pagesmith/core` as the headless content layer. If a project needs site-building concerns, choose `@pagesmith/site` as the app-facing package instead:

- JSX runtime: `@pagesmith/site/jsx-runtime`
- CSS builder + CSS bundles: `@pagesmith/site/css` and `@pagesmith/site/css/*`
- Runtime JS helpers: `@pagesmith/site/runtime` and `@pagesmith/site/runtime/*`
- SSG helpers: `@pagesmith/site/vite` and `@pagesmith/site/ssg-utils`
- CLI and preset loading: `pagesmith` from `@pagesmith/site`

Framework-hosted apps that only need the shipped prose/code-block presentation layer can either stay on `@pagesmith/core` alone or move up to `@pagesmith/site` when they want those shared CSS/runtime modules too.