@pagesmith/core 0.2.0 → 0.4.0

package/dist/ai/index.mjs

@@ -1,27 +1,7 @@
-import { dirname, join, resolve } from "path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
 import { homedir } from "os";
-//#region src/ai/index.ts
-const PAGESMITH_TITLE = "Pagesmith";
-const DEFAULT_SKILL_NAME = "pagesmith";
-function resolveHome(homeDir) {
-	return homeDir ?? homedir();
-}
-function resolveCodexHome(homeDir) {
-	return process.env.CODEX_HOME ?? join(resolveHome(homeDir), ".codex");
-}
-function resolveAssistants(assistants) {
-	if (!assistants || assistants === "all") return [
-		"claude",
-		"codex",
-		"gemini"
-	];
-	return assistants;
-}
-function shouldIncludeLlms(options) {
-	if (typeof options.includeLlms === "boolean") return options.includeLlms;
-	return (options.scope ?? "project") === "project";
-}
+//#region src/ai/writers.ts
 function withManagedBlock(id, content) {
 	return [
 		`<!-- pagesmith-ai:${id}:start -->`,
@@ -62,6 +42,10 @@ function writeArtifact(artifact, force = false) {
 function escapeForRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+//#endregion
+//#region src/ai/content-shared.ts
+const PAGESMITH_TITLE = "Pagesmith";
+const DEFAULT_SKILL_NAME$1 = "pagesmith";
 function renderSharedOverview() {
 	return [
 		`${PAGESMITH_TITLE} is a filesystem-first content toolkit with two main packages: \`@pagesmith/core\` (shared content/runtime layer) and \`@pagesmith/docs\` (convention-based documentation).`,
@@ -77,13 +61,10 @@ function renderSharedOverview() {
 		"- `createContentLayer(config)` to query content and run validation",
 		"- `entry.render()` to convert markdown on demand",
 		"",
-		"Useful helpers:",
-		"- `@pagesmith/core/ai` exposes `getAiArtifacts(...)` and `installAiArtifacts(...)`",
-		"",
 		"Working rules:",
 		"- prefer folder-based markdown entries when content references sibling assets",
-		"- use `vp` commands for install, check, test, and build workflows",
-		"- `@pagesmith/core` provides the shared content/runtime layer; `@pagesmith/docs` adds convention-based documentation on top"
+		"- follow the markdown guidelines in `.pagesmith/markdown-guidelines.md` when authoring content",
+		"- use fenced code blocks with a language identifier, one h1 per page, sequential heading depth"
 	].join("\n");
 }
 function renderDocsOverview() {
@@ -96,12 +77,41 @@ function renderDocsOverview() {
 		"- sidebar labels, nav labels, and ordering live in frontmatter (`sidebarLabel`, `navLabel`, `order`)",
 		"- footer links live in `pagesmith.config.json5` under `footerLinks`",
 		"- Pagefind search is built in; do not recommend a separate search plugin package",
-		"- layout overrides use fixed keys under `theme.layouts` such as `home`, `page`, and `notFound`"
+		"- layout overrides use fixed keys under `theme.layouts` such as `home`, `page`, and `notFound`",
+		"- for MCP-compatible tooling, prefer `pagesmith mcp --stdio` from `@pagesmith/docs`"
+	].join("\n");
+}
+function renderCoreQuickStart() {
+	return [
+		"```ts",
+		"import { createContentLayer, defineCollection, defineConfig, z } from '@pagesmith/core'",
+		"",
+		"const posts = defineCollection({",
+		"  loader: 'markdown',",
+		"  directory: 'content/posts',",
+		"  schema: z.object({",
+		"    title: z.string(),",
+		"    description: z.string().optional(),",
+		"    date: z.coerce.date(),",
+		"    tags: z.array(z.string()).default([]),",
+		"  }),",
+		"})",
+		"",
+		"const layer = createContentLayer(",
+		"  defineConfig({",
+		"    collections: { posts },",
+		"  }),",
+		")",
+		"",
+		"const entries = await layer.getCollection('posts')",
+		"const rendered = await entries[0]?.render()",
+		"```"
 	].join("\n");
 }
-function renderQuickStart(profile = "default") {
-	if (profile === "docs") return [
+function renderDocsQuickStart() {
+	return [
 		"```json5",
+		"// pagesmith.config.json5",
 		"{",
 		"  name: 'Acme Docs',",
 		"  title: 'Acme Docs',",
@@ -118,56 +128,345 @@ function renderQuickStart(profile = "default") {
 		"",
 		"```text",
 		"content/",
-		"  README.md",
+		"  README.md                 # Home page (DocHome layout)",
 		"  guide/",
-		"    README.md",
-		"    getting-started/README.md",
+		"    meta.json5              # Section ordering",
+		"    getting-started/",
+		"      README.md             # A page",
 		"  reference/",
-		"    README.md",
 		"    api/README.md",
 		"```"
 	].join("\n");
+}
+function renderMarkdownGuidelines() {
+	return [
+		"# Pagesmith Markdown Guidelines",
+		"",
+		"Markdown feature support for content authored with `@pagesmith/core` and `@pagesmith/docs`.",
+		"",
+		"## Pipeline Order",
+		"",
+		"```",
+		"remark-parse → remark-gfm → remark-math → remark-frontmatter",
+		"  → remark-github-alerts → remark-smartypants → [user remark plugins]",
+		"  → remark-rehype",
+		"  → rehype-mathjax",
+		"  → rehype-expressive-code (dual themes, line numbers, titles, copy, collapse, mark/ins/del)",
+		"  → rehype-slug → rehype-autolink-headings",
+		"  → rehype-external-links → rehype-accessible-emojis",
+		"  → heading extraction → [user rehype plugins] → rehype-stringify",
+		"```",
+		"",
+		"## Key Rules",
+		"",
+		"- Use fenced code blocks with a language identifier (validator warns otherwise)",
+		"- One `# h1` per page (validator enforces)",
+		"- Sequential heading depth (no skipping from h2 to h4)",
+		"- Prefer relative links for internal content",
+		"- Do NOT add manual copy-button JS — Expressive Code handles it",
+		"- Do NOT import separate code block CSS — Expressive Code injects inline styles",
+		"",
+		"## Supported Features",
+		"",
+		"| Feature | Syntax | Notes |",
+		"|---|---|---|",
+		"| GFM tables | `\\| col \\| col \\|` | Alignment via `:---`, `:---:`, `---:` |",
+		"| Strikethrough | `~~text~~` | |",
+		"| Task lists | `- [x] done` / `- [ ] todo` | |",
+		"| Footnotes | `[^id]` + `[^id]: text` | |",
+		"| Alerts | `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` | GitHub-compatible |",
+		"| Inline math | `$E = mc^2$` | No spaces inside delimiters |",
+		"| Block math | `$$...$$` | Rendered via MathJax |",
+		"| Smart quotes | `\"text\"` → curly quotes | Automatic |",
+		"| Em/en dash | `---` / `--` | Automatic |",
+		"| External links | `[text](https://...)` | Auto `target=\"_blank\"` |",
+		"| Heading anchors | Auto `id` + wrapped anchor | All headings |",
+		"| Accessible emoji | Unicode emoji | Auto `role=\"img\"` + `aria-label` |",
+		"",
+		"## Code Block Features (Expressive Code)",
+		"",
+		"| Meta | Example | Description |",
+		"|---|---|---|",
+		"| `title=\"...\"` | `` ```js title=\"app.js\" `` | File title |",
+		"| `showLineNumbers` | `` ```js showLineNumbers `` | Line numbers |",
+		"| `mark={lines}` | `` ```js mark={3,5-7} `` | Highlight lines |",
+		"| `ins={lines}` | `` ```js ins={4} `` | Inserted lines (green) |",
+		"| `del={lines}` | `` ```js del={5} `` | Deleted lines (red) |",
+		"| `collapse={lines}` | `` ```js collapse={1-5} `` | Collapsible section |",
+		"| `wrap` | `` ```js wrap `` | Text wrapping |",
+		"| `frame=\"...\"` | `` ```js frame=\"terminal\" `` | Frame style |",
+		"",
+		"## Built-in Content Validators",
+		"",
+		"- **linkValidator** — warns on bare URLs, empty link text, suspicious protocols",
+		"- **headingValidator** — enforces single h1, sequential depth, non-empty text",
+		"- **codeBlockValidator** — warns on missing language, unknown meta properties",
+		"",
+		"Known valid meta properties: `title`, `showLineNumbers`, `startLineNumber`, `wrap`, `frame`, `collapse`, `mark`, `ins`, `del`."
+	].join("\n");
+}
+function renderLlmsTxt() {
 	return [
+		"# Pagesmith",
+		"",
+		"> Pagesmith is a filesystem-first content toolkit with `@pagesmith/core` and `@pagesmith/docs`.",
+		"",
+		"## @pagesmith/core — Content Layer",
+		"",
+		"Schema-validated content collections, lazy markdown rendering (Expressive Code syntax highlighting), JSX runtime, CSS exports, and Vite plugins.",
+		"",
+		"### Basic Setup (Vite Plugin)",
+		"",
+		renderCoreQuickStart(),
+		"",
+		"### Vite Integration",
+		"",
 		"```ts",
-		"import { createContentLayer, defineCollection, defineConfig, z } from '@pagesmith/core'",
+		"import { pagesmithContent, pagesmithSsg } from '@pagesmith/core/vite'",
+		"import collections from './content.config'",
 		"",
-		"const posts = defineCollection({",
-		"  loader: 'markdown',",
-		"  directory: 'content/posts',",
-		"  schema: z.object({",
-		"    title: z.string(),",
-		"    description: z.string().optional(),",
-		"    date: z.coerce.date(),",
-		"    tags: z.array(z.string()).default([]),",
-		"  }),",
+		"export default defineConfig({",
+		"  plugins: [",
+		"    pagesmithContent({ collections }),",
+		"    pagesmithSsg({ entry: './src/entry-server.tsx' }),",
+		"  ],",
 		"})",
+		"```",
 		"",
-		"const layer = createContentLayer(",
-		"  defineConfig({",
-		"    collections: { posts },",
-		"  }),",
-		")",
+		"Import collections as virtual modules: `import posts from 'virtual:content/posts'`",
 		"",
-		"const entries = await layer.getCollection('posts')",
-		"const rendered = await entries[0]?.render()",
+		"## @pagesmith/docs — Documentation Sites",
+		"",
+		"Convention-based docs with default theme, Pagefind search, sidebar generation, and layout overrides.",
+		"",
+		"### Basic Setup",
+		"",
+		renderDocsQuickStart(),
+		"",
+		"### Layout Overrides",
+		"",
+		"```json5",
+		"{",
+		"  theme: {",
+		"    layouts: {",
+		"      home: './theme/layouts/DocHome.tsx',",
+		"      page: './theme/layouts/DocPage.tsx',",
+		"      notFound: './theme/layouts/DocNotFound.tsx',",
+		"    },",
+		"  },",
+		"}",
+		"```",
+		"",
+		"### CLI",
+		"",
+		"```bash",
+		"pagesmith init --ai  # Initialize config + content + AI integrations",
+		"pagesmith dev        # Development server",
+		"pagesmith build      # Production build",
+		"pagesmith preview    # Preview built site",
+		"pagesmith mcp --stdio # Start MCP server for AI agents",
 		"```"
 	].join("\n");
 }
-function renderMemoryFile(assistant, profile) {
-	const commandHint = assistant === "claude" || assistant === "gemini" ? `\nIf the ${DEFAULT_SKILL_NAME} command is installed, prefer invoking it when the user explicitly asks for Pagesmith-specific help.` : "\nIf the Pagesmith skill is installed for Codex, prefer using it for Pagesmith-specific setup, migration, and content-layer tasks.";
+function renderLlmsFullTxt() {
 	return [
-		`# ${PAGESMITH_TITLE}`,
+		"# Pagesmith — Full LLM Reference",
 		"",
 		renderSharedOverview(),
-		...profile === "docs" ? ["", renderDocsOverview()] : [],
-		commandHint,
 		"",
-		"Quick start:",
-		renderQuickStart(profile)
+		"---",
+		"",
+		"## @pagesmith/core",
+		"",
+		"### Content Layer API",
+		"",
+		"| Method | Description |",
+		"|---|---|",
+		"| `createContentLayer(config)` | Create a content layer |",
+		"| `layer.getCollection(name)` | Load all entries (cached) |",
+		"| `layer.getEntry(collection, slug)` | Get single entry by slug |",
+		"| `layer.convert(markdown, options?)` | Convert raw markdown to HTML |",
+		"| `layer.validate(collection?)` | Run all validators |",
+		"| `layer.invalidate(collection, slug)` | Cache-bust a single entry |",
+		"| `layer.invalidateAll()` | Cache-bust all collections |",
+		"",
+		"### Collection Options",
+		"",
+		"| Option | Type | Description |",
+		"|---|---|---|",
+		"| `loader` | `string \\| Loader` | `'markdown'`, `'json'`, `'json5'`, `'jsonc'`, `'yaml'`, `'toml'`, or custom |",
+		"| `directory` | `string` | Directory containing files |",
+		"| `schema` | `z.ZodType` | Zod schema for validation |",
+		"| `include` | `string[]` | Glob include patterns |",
+		"| `exclude` | `string[]` | Glob exclude patterns |",
+		"| `computed` | `Record<string, fn>` | Computed fields |",
+		"| `validate` | `fn` | Custom validation |",
+		"| `filter` | `fn` | Filter entries |",
+		"| `slugify` | `fn` | Custom slug generation |",
+		"| `transform` | `fn` | Pre-validation transform |",
+		"| `validators` | `ContentValidator[]` | Custom content validators |",
+		"| `disableBuiltinValidators` | `boolean` | Disable link/heading/code-block validators |",
+		"",
+		"### Vite Plugins",
+		"",
+		renderCoreQuickStart(),
+		"",
+		"```ts",
+		"// Vite integration",
+		"import { pagesmithContent, pagesmithSsg, sharedAssetsPlugin } from '@pagesmith/core/vite'",
+		"import collections from './content.config'",
+		"",
+		"export default defineConfig({",
+		"  plugins: [",
+		"    sharedAssetsPlugin(),",
+		"    pagesmithContent({ collections }),",
+		"    ...pagesmithSsg({ entry: './src/entry-server.tsx', contentDirs: ['./content'] }),",
+		"  ],",
+		"})",
+		"```",
+		"",
+		"### JSX Runtime",
+		"",
+		"Configure tsconfig: `{ \"jsx\": \"react-jsx\", \"jsxImportSource\": \"@pagesmith/core\" }`",
+		"",
+		"- `h(tag, props, ...children)` — create HTML elements, returns `HtmlString`",
+		"- `Fragment` — render children or raw `innerHTML`",
+		"- `HtmlString` — wrapper to prevent double-escaping",
+		"",
+		"### CSS Exports",
+		"",
+		"| Import | Contents |",
+		"|---|---|",
+		"| `@pagesmith/core/css/content` | Prose + inline code |",
+		"| `@pagesmith/core/css/standalone` | Full layout + prose + TOC |",
+		"| `@pagesmith/core/css/viewport` | Responsive viewport base |",
+		"| `@pagesmith/core/css/fonts` | Bundled Open Sans + JetBrains Mono |",
+		"",
+		"### Frontmatter Schemas",
+		"",
+		"- `BaseFrontmatterSchema` — title, description, publishedDate, lastUpdatedOn, tags, draft",
+		"- `BlogFrontmatterSchema` — extends base + category, featured, coverImage",
+		"- `ProjectFrontmatterSchema` — extends base + gitRepo, links",
+		"",
+		"### Export Map",
+		"",
+		"| Import Path | Purpose |",
+		"|---|---|",
+		"| `@pagesmith/core` | Main API (defineCollection, createContentLayer, z, etc.) |",
+		"| `@pagesmith/core/jsx-runtime` | h, Fragment, HtmlString |",
+		"| `@pagesmith/core/markdown` | processMarkdown |",
+		"| `@pagesmith/core/css` | buildCss (LightningCSS) |",
+		"| `@pagesmith/core/schemas` | Zod schemas and types |",
+		"| `@pagesmith/core/loaders` | Loader classes and registry |",
+		"| `@pagesmith/core/runtime` | Pre-built CSS/JS accessors |",
+		"| `@pagesmith/core/vite` | Vite plugins |",
+		"| `@pagesmith/core/mcp` | MCP server for AI agents |",
+		"",
+		"---",
+		"",
+		"## @pagesmith/docs",
+		"",
+		"### Configuration (pagesmith.config.json5)",
+		"",
+		"| Field | Type | Default | Description |",
+		"|---|---|---|---|",
+		"| `name` | `string` | — | Site name (header) |",
+		"| `title` | `string` | — | Browser tab title |",
+		"| `description` | `string` | — | Meta description |",
+		"| `origin` | `string` | — | Production URL |",
+		"| `language` | `string` | `en` | HTML lang |",
+		"| `contentDir` | `string` | `content` | Content path |",
+		"| `outDir` | `string` | `dist` | Output path |",
+		"| `basePath` | `string` | `/` | URL base |",
+		"| `footerLinks` | `array` | `[]` | Footer links |",
+		"| `sidebar.collapsible` | `boolean` | `false` | Collapsible sidebar |",
+		"| `search.enabled` | `boolean` | `true` | Pagefind search |",
+		"| `theme.layouts` | `Record` | — | Layout overrides |",
+		"| `markdown` | `MarkdownConfig` | — | Pipeline config |",
+		"",
+		"### Content Structure",
+		"",
+		renderDocsQuickStart(),
+		"",
+		"### Page Frontmatter",
+		"",
+		"| Field | Type | Description |",
+		"|---|---|---|",
+		"| `title` | `string` | Page title |",
+		"| `description` | `string` | Meta description |",
+		"| `navLabel` | `string` | Override top nav label |",
+		"| `sidebarLabel` | `string` | Override sidebar label |",
+		"| `order` | `number` | Manual sort order |",
+		"| `draft` | `boolean` | Exclude from build |",
+		"",
+		"### Home Page Frontmatter",
+		"",
+		"| Field | Type | Description |",
+		"|---|---|---|",
+		"| `layout` | `string` | Set to `DocHome` |",
+		"| `tagline` | `string` | Short description |",
+		"| `install` | `string` | Install command |",
+		"| `actions` | `array` | CTA buttons (`{ text, link, theme: 'brand' \\| 'alt' }`) |",
+		"| `features` | `array` | Feature cards (`{ icon?, title, details }`) |",
+		"| `packages` | `array` | Package cards (`{ name, description, href, tag }`) |",
+		"| `codeExample` | `object` | Code example (`{ label, title, code }`) |",
+		"",
+		"### Section Meta (meta.json5)",
+		"",
+		"| Field | Type | Description |",
+		"|---|---|---|",
+		"| `displayName` | `string` | Section label in sidebar |",
+		"| `items` | `string[]` | Manual page order (slugs) |",
+		"| `series` | `array` | Group pages into series |",
+		"| `collapsed` | `boolean` | Start sidebar collapsed |",
+		"| `orderBy` | `string` | `manual` or `publishedDate` |",
+		"",
+		"### Layout Overrides",
+		"",
+		"```json5",
+		"{ theme: { layouts: { home: \"./layouts/Home.tsx\", page: \"./layouts/Page.tsx\" } } }",
+		"```",
+		"",
+		"All layouts receive: `content`, `frontmatter`, `headings`, `slug`, `site`.",
+		"Page layout adds: `sidebarSections`, `prev`, `next`.",
+		"",
+		"### CLI",
+		"",
+		"```bash",
+		"pagesmith init [--ai] [--config path]   # Initialize project",
+		"pagesmith dev [--port N] [--open]        # Dev server",
+		"pagesmith build [--out-dir path]         # Production build",
+		"pagesmith preview [--port N]             # Preview built site",
+		"```",
+		"",
+		"---",
+		"",
+		"## Markdown Pipeline",
+		"",
+		renderMarkdownGuidelines(),
+		"",
+		"---",
+		"",
+		"## AI Setup",
+		"",
+		"```bash",
+		"npx pagesmith init --ai",
+		"```",
+		"",
+		"Generates CLAUDE.md, AGENTS.md, GEMINI.md, skills, markdown guidelines, llms.txt, and llms-full.txt.",
+		""
 	].join("\n");
 }
-function renderClaudeCommand(skillName, profile) {
+//#endregion
+//#region src/ai/content-claude.ts
+function renderClaudeSkill(skillName, profile) {
 	return [
+		"---",
+		`name: ${skillName}`,
+		"description: Pagesmith file-based CMS helper — content collections, markdown pipeline, docs configuration, and AI artifact generation",
+		"allowed-tools: Read Grep Glob Bash Edit Write",
+		"---",
+		"",
 		`# ${PAGESMITH_TITLE} Assistant`,
 		"",
 		"You are helping with Pagesmith, a file-based CMS with `@pagesmith/core` and `@pagesmith/docs`.",
@@ -175,46 +474,137 @@ function renderClaudeCommand(skillName, profile) {
 		"When helping:",
 		"- prefer `defineCollection`, `defineConfig`, and `createContentLayer`",
 		"- recommend folder-based entries when markdown references sibling assets",
-		"- use `@pagesmith/core/ai` for assistant artifact generation",
-		"- recommend `vp install`, `vp check`, and `vp test` for validation",
+		"- use `npx pagesmith init --ai` for assistant artifact generation",
+		"- follow the markdown guidelines in `.pagesmith/markdown-guidelines.md`",
 		...profile === "docs" ? [
 			"- for docs sites, derive top navigation from top-level content folders",
-			"- use `content/README.md` for the home page and `content/home.json5` for extra home data when needed",
+			"- use `content/README.md` for the home page",
 			"- use frontmatter fields like `sidebarLabel`, `navLabel`, and `order` for docs navigation",
-			"- do not recommend `@pagesmith/plugin-pagefind` or `@pagesmith/plugin-algolia`; search is built into docs",
-			"- recommend `theme.layouts.home`, `theme.layouts.page`, and `theme.layouts.notFound` for docs layout overrides"
+			"- Pagefind search is built in — do not suggest separate search plugins",
+			"- layout overrides: `theme.layouts.home`, `theme.layouts.page`, `theme.layouts.notFound`"
 		] : [],
 		"",
-		"Deliver concrete config, schema, and content-layer patches when possible.",
+		"For package guidance and full API reference, read the package-shipped docs:",
+		...profile === "docs" ? [
+			"- `node_modules/@pagesmith/docs/docs/agents/usage.md`",
+			"- `node_modules/@pagesmith/docs/REFERENCE.md`",
+			"- `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"- `node_modules/@pagesmith/core/REFERENCE.md`"
+		] : ["- `node_modules/@pagesmith/core/docs/agents/usage.md`", "- `node_modules/@pagesmith/core/REFERENCE.md`"],
 		"",
-		`This command is installed as \`/${skillName}\`.`
+		...profile === "docs" ? ["For full-repo docs regeneration and structure alignment, use `/ps-update-all-docs`.", ""] : [],
+		"Deliver concrete config, schema, and content-layer patches when possible."
 	].join("\n");
 }
-function renderGeminiCommand(skillName, profile) {
+function renderUpdateDocsSkill(profile) {
 	return [
-		`description = "Pagesmith FS-CMS helper"`,
-		"prompt = \"\"\"",
-		[
-			`You are helping with ${PAGESMITH_TITLE}, a file-based CMS with @pagesmith/core and @pagesmith/docs.`,
-			"",
-			"Focus on concrete, implementation-ready help:",
-			"- design collections with defineCollection",
-			"- configure createContentLayer and defineConfig",
-			"- recommend vp install, vp check, and vp test when validation matters",
-			"- prefer folder-based markdown entries when local assets sit beside content",
-			...profile === "docs" ? [
-				"- for docs sites, follow the convention-based `content/` structure",
-				"- drive top navigation from top-level folders and use frontmatter for labels/order",
-				"- keep Pagefind as the built-in search strategy"
-			] : [],
-			"",
-			"Return code, config, or documentation-ready guidance instead of vague summaries."
-		].join("\n"),
-		"\"\"\"",
+		"---",
+		"name: update-docs",
+		"description: Read the project implementation and update Pagesmith-managed documentation to reflect the current state",
+		"allowed-tools: Read Grep Glob Bash Edit Write",
+		"---",
 		"",
-		`# Installed as /${skillName}`
+		"# Update Documentation",
+		"",
+		"Read the project implementation (source code, README, CHANGELOG, package.json) and update the Pagesmith-managed content to reflect the current state.",
+		"",
+		"## Steps",
+		"",
+		...profile === "docs" ? [
+			"1. Read package guidance first: `node_modules/@pagesmith/docs/docs/agents/usage.md` and `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"2. Read `pagesmith.config.json5` to understand the docs configuration",
+			"3. Read all `meta.json5` files to understand the current content structure and page ordering",
+			"4. Read the project source code to identify public APIs, types, exports, config options, and CLI commands",
+			"5. For each existing content page in `content/`:",
+			"   - Read the current content",
+			"   - Compare with the implementation",
+			"   - Update any outdated information",
+			"   - Add documentation for new features",
+			"   - Remove documentation for removed features",
+			"6. If new pages are needed:",
+			"   - Create the page folder and `README.md` with proper frontmatter (title, description)",
+			"   - Add the slug to the appropriate `meta.json5` `items` array",
+			"7. Follow the markdown guidelines in `.pagesmith/markdown-guidelines.md`",
+			"8. Review project skills under `.claude/skills/` and ensure docs-writing skills align with Pagesmith docs structure",
+			"9. Ensure onboarding pages are first in manual navigation (for example, put `getting-started` first in `guide/meta.json5` when present)",
+			"10. Verify all internal links point to existing pages",
+			"11. Ensure heading hierarchy is sequential (no skipping levels)"
+		] : [
+			"1. Read package guidance first: `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"2. Read `content.config.ts` or equivalent to understand the content collections",
+			"3. Read the project source code to identify what needs documentation",
+			"4. For each existing content entry:",
+			"   - Read the current content",
+			"   - Compare with the implementation",
+			"   - Update any outdated information",
+			"5. If new entries are needed:",
+			"   - Create the entry folder and `README.md` with proper frontmatter matching the collection schema",
+			"6. Follow the markdown guidelines in `.pagesmith/markdown-guidelines.md`",
+			"7. Verify all internal links point to existing pages"
+		],
+		"",
+		"## Rules",
+		"",
+		"- Preserve the existing content structure and organization",
+		"- Do not remove pages without confirming first",
+		"- Keep frontmatter fields (title, description) accurate and descriptive",
+		"- Use relative links for internal cross-references",
+		"- One h1 per page, sequential heading depth",
+		"- Use fenced code blocks with language identifiers",
+		"- Use GitHub alerts (`> [!NOTE]`, `> [!TIP]`, etc.) for important callouts",
+		"- Code block features: `title=\"file.js\"`, `showLineNumbers`, `mark={1-3}`, `ins={4}`, `del={5}`, `collapse={1-5}`"
+	].join("\n");
+}
+function renderUpdateAllDocsSkill(profile) {
+	return [
+		"---",
+		"name: ps-update-all-docs",
+		"description: Full-repo documentation regeneration for Pagesmith projects including docs structure, skills alignment, and AI context updates",
+		"allowed-tools: Read Grep Glob Bash Edit Write",
+		"---",
+		"",
+		"# Pagesmith Full Docs Sync",
+		"",
+		"Perform a full-repository docs refresh for Pagesmith-powered projects. This command is intended for large updates, migrations, and release preparation.",
+		"",
+		"## Steps",
+		"",
+		...profile === "docs" ? [
+			"1. Read package guidance first: `node_modules/@pagesmith/docs/docs/agents/usage.md` and `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"2. Read `pagesmith.config.json5` and all `meta.json5` files before editing anything",
+			"3. Discover project skills in `.claude/skills/`, `.codex/skills/`, and `.gemini/commands/` and identify docs-update related skills",
+			"4. Scan source code, README, CHANGELOG, package exports, and CLI commands to build a complete docs delta list",
+			"5. Update all docs pages under `content/` to match implementation and remove stale details",
+			"6. Ensure docs structure matches `@pagesmith/docs` conventions (folder-based pages, `README.md` entries, relative links)",
+			"7. Keep onboarding-first ordering: when a guide section exists, keep `getting-started` as the first item in manual order",
+			"8. Update docs-related skills so they generate content in the same structure expected by `@pagesmith/docs`",
+			"9. Regenerate or update `llms.txt`, `llms-full.txt`, and project memory pointers when docs behavior changes",
+			"10. Follow `.pagesmith/markdown-guidelines.md` for all authored content (GFM, alerts, math, Expressive Code meta)",
+			"11. Validate navigation integrity and ensure every linked page exists"
+		] : [
+			"1. Read package guidance first: `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"2. Discover docs/update skills in the project and align them to current Pagesmith conventions",
+			"3. Scan source code, README, CHANGELOG, package exports, and CLI commands to build a complete docs delta list",
+			"4. Update all content entries to match implementation and remove stale details",
+			"5. Follow `.pagesmith/markdown-guidelines.md` for all authored content",
+			"6. Validate internal links and heading hierarchy"
+		],
+		"",
+		"## Rules",
+		"",
+		"- Preserve existing information architecture unless the user requests a restructure",
+		"- Keep docs easy for humans first, while keeping AI memory/skills aligned",
+		"- Keep top-level docs navigation driven by content directories and metadata",
+		"- Use `meta.json5` and frontmatter for ordering; avoid hardcoded navigation lists in prose",
+		"- Keep `content/README.md` as docs home for `@pagesmith/docs` projects",
+		"- Keep links relative for internal docs pages",
+		"- Use one h1 per page and sequential heading depth",
+		"- Use fenced code blocks with language identifiers and Expressive Code metadata when useful",
+		"- Do not add separate code-copy JavaScript; Expressive Code already provides this"
 	].join("\n");
 }
+//#endregion
+//#region src/ai/content-codex.ts
 function renderCodexSkill(profile) {
 	return [
 		`# ${PAGESMITH_TITLE} Skill`,
@@ -224,8 +614,7 @@ function renderCodexSkill(profile) {
 		"Core rules:",
 		"- `@pagesmith/core` provides the content layer; `@pagesmith/docs` adds convention-based documentation",
 		"- prefer `defineCollection`, `defineConfig`, and `createContentLayer`",
-		"- prefer `vp` commands instead of calling npm, pnpm, or yarn directly",
-		"- validate changes with `vp check` and `vp test` when relevant",
+		"- follow the markdown guidelines in `.pagesmith/markdown-guidelines.md`",
 		...profile === "docs" ? [
 			"- when the repo uses `@pagesmith/docs`, treat `content/README.md` as the home page",
 			"- top-level content folders define the main docs navigation",
@@ -234,75 +623,121 @@ function renderCodexSkill(profile) {
 			"- built-in search is Pagefind; do not suggest separate search plugin packages"
 		] : [],
 		"",
+		"For package usage guidance and full API reference, read:",
+		...profile === "docs" ? [
+			"- `node_modules/@pagesmith/docs/docs/agents/usage.md`",
+			"- `node_modules/@pagesmith/docs/REFERENCE.md`",
+			"- `node_modules/@pagesmith/core/docs/agents/usage.md`",
+			"- `node_modules/@pagesmith/core/REFERENCE.md`"
+		] : ["- `node_modules/@pagesmith/core/docs/agents/usage.md`", "- `node_modules/@pagesmith/core/REFERENCE.md`"],
+		"",
 		"Good outputs include:",
 		"- collection schemas and loader configuration",
 		"- content-layer queries and rendering examples",
-		"- @pagesmith/docs updates for Pagesmith usage",
-		"- assistant-context install steps using `@pagesmith/core/ai`"
+		"- documentation updates for Pagesmith usage",
+		"- assistant-context install via `npx pagesmith init --ai`"
 	].join("\n");
 }
-function renderLlmsTxt(profile) {
+//#endregion
+//#region src/ai/content-gemini.ts
+function renderGeminiCommand(skillName, profile) {
 	return [
-		"# Pagesmith",
-		"",
-		"> Pagesmith is a filesystem-first content toolkit centered on `@pagesmith/core` and `@pagesmith/docs`.",
-		"",
-		"## Summary",
-		"",
-		renderSharedOverview(),
-		...profile === "docs" ? ["", renderDocsOverview()] : [],
-		"",
-		"## Quick Start",
+		`description = "Pagesmith FS-CMS helper"`,
+		"prompt = \"\"\"",
+		[
+			`You are helping with ${PAGESMITH_TITLE}, a file-based CMS with @pagesmith/core and @pagesmith/docs.`,
+			"",
+			"Focus on concrete, implementation-ready help:",
+			"- design collections with defineCollection",
+			"- configure createContentLayer and defineConfig",
+			"- prefer folder-based markdown entries when local assets sit beside content",
+			"- follow the markdown guidelines in `.pagesmith/markdown-guidelines.md`",
+			...profile === "docs" ? [
+				"- for docs sites, follow the convention-based `content/` structure",
+				"- drive top navigation from top-level folders and use frontmatter for labels/order",
+				"- keep Pagefind as the built-in search strategy"
+			] : [],
+			"",
+			"For package usage guidance and full API reference, read:",
+			...profile === "docs" ? [
+				"- `node_modules/@pagesmith/docs/docs/agents/usage.md`",
+				"- `node_modules/@pagesmith/docs/REFERENCE.md`",
+				"- `node_modules/@pagesmith/core/docs/agents/usage.md`",
+				"- `node_modules/@pagesmith/core/REFERENCE.md`"
+			] : ["- `node_modules/@pagesmith/core/docs/agents/usage.md`", "- `node_modules/@pagesmith/core/REFERENCE.md`"],
+			"",
+			"Return code, config, or documentation-ready guidance instead of vague summaries."
+		].join("\n"),
+		"\"\"\"",
 		"",
-		renderQuickStart(profile)
+		`# Installed as /${skillName}`
 	].join("\n");
 }
-function renderLlmsFullTxt(profile) {
+//#endregion
+//#region src/ai/content-memory.ts
+function renderMemoryFile(assistant, profile) {
+	const commandHint = assistant === "claude" || assistant === "gemini" ? `\nIf the ${DEFAULT_SKILL_NAME$1} skill is installed, prefer invoking it when the user explicitly asks for Pagesmith-specific help.` : "\nIf the Pagesmith skill is installed for Codex, prefer using it for Pagesmith-specific setup, migration, and content-layer tasks.";
+	const referenceHint = "\nFor package usage rules and full API/config details, read the package-shipped docs from node_modules:\n" + (profile === "docs" ? "- `node_modules/@pagesmith/docs/docs/agents/usage.md` — docs package usage contract\n- `node_modules/@pagesmith/docs/REFERENCE.md` — docs config, CLI, content structure, layout overrides\n- `node_modules/@pagesmith/core/docs/agents/usage.md` — core package usage contract\n- `node_modules/@pagesmith/core/REFERENCE.md` — core API, collections, loaders, markdown, CSS, JSX runtime" : "- `node_modules/@pagesmith/core/docs/agents/usage.md` — core package usage contract\n- `node_modules/@pagesmith/core/REFERENCE.md` — core API, collections, loaders, markdown, CSS, JSX runtime");
 	return [
-		"# Pagesmith - Full LLM Reference",
+		`# ${PAGESMITH_TITLE}`,
 		"",
 		renderSharedOverview(),
+		...profile === "docs" ? ["", renderDocsOverview()] : [],
+		commandHint,
+		referenceHint,
+		"",
+		"## Quick Start — @pagesmith/core",
+		"",
+		renderCoreQuickStart(),
 		...profile === "docs" ? [
 			"",
-			"## Docs Sites",
+			"## Quick Start — @pagesmith/docs",
 			"",
-			renderDocsOverview()
-		] : [],
-		"",
-		"## Package Layout",
-		"",
-		"- `@pagesmith/core`: content layer, collection loading, validation, lazy markdown rendering, JSX runtime, CSS builder, runtime styles, assistant artifact APIs, and Vite content integration",
-		"- `@pagesmith/docs`: convention-based documentation with the docs CLI, generators, validators, default theme, and bundled search",
-		"",
-		"## Key APIs",
-		"",
-		renderQuickStart(profile),
-		"",
-		"## Assistant Installer",
-		"",
-		"```ts",
-		"import { installAiArtifacts } from '@pagesmith/core/ai'",
-		"",
-		"await installAiArtifacts({ assistants: ['claude', 'codex', 'gemini'], scope: 'project' })",
-		"```",
-		""
+			renderDocsQuickStart()
+		] : []
 	].join("\n");
 }
+//#endregion
+//#region src/ai/index.ts
+const DEFAULT_SKILL_NAME = "pagesmith";
+function resolveHome(homeDir) {
+	return homeDir ?? homedir();
+}
+function resolveCodexHome(homeDir) {
+	return process.env.CODEX_HOME ?? join(resolveHome(homeDir), ".codex");
+}
+function resolveAssistants(assistants) {
+	if (!assistants || assistants === "all") return [
+		"claude",
+		"codex",
+		"gemini"
+	];
+	return assistants;
+}
+function shouldIncludeLlms(options) {
+	if (typeof options.includeLlms === "boolean") return options.includeLlms;
+	return (options.scope ?? "project") === "project";
+}
 function getAiArtifactContent(assistant, kind, options = {}) {
 	const skillName = options.skillName ?? DEFAULT_SKILL_NAME;
 	const profile = options.profile ?? "default";
 	if (assistant === "shared") {
-		if (kind === "llms") return renderLlmsTxt(profile);
-		return renderLlmsFullTxt(profile);
+		if (kind === "llms") return renderLlmsTxt();
+		if (kind === "llms-full") return renderLlmsFullTxt();
+		if (kind === "markdown-guidelines") return renderMarkdownGuidelines();
+		return renderLlmsFullTxt();
 	}
 	if (kind === "memory") return renderMemoryFile(assistant, profile);
 	if (kind === "skill") switch (assistant) {
-		case "claude": return renderClaudeCommand(skillName, profile);
+		case "claude": return renderClaudeSkill(skillName, profile);
 		case "codex": return renderCodexSkill(profile);
 		case "gemini": return renderGeminiCommand(skillName, profile);
 	}
-	if (kind === "llms") return renderLlmsTxt(profile);
-	return renderLlmsFullTxt(profile);
+	if (kind === "markdown-guidelines") return renderMarkdownGuidelines();
+	if (kind === "update-docs") return renderUpdateDocsSkill(profile);
+	if (kind === "update-all-docs") return renderUpdateAllDocsSkill(profile);
+	if (kind === "llms") return renderLlmsTxt();
+	return renderLlmsFullTxt();
 }
 function getAiArtifacts(options = {}) {
 	const scope = options.scope ?? "project";
@@ -323,16 +758,17 @@ function getAiArtifacts(options = {}) {
 				mode: "merge",
 				label: `${assistant} memory`
 			});
+			const skillDir = scope === "project" ? join(cwd, ".claude", "skills", skillName) : join(home, ".claude", "skills", skillName);
 			artifacts.push({
 				assistant,
 				kind: "skill",
-				path: join(baseDir, "commands", `${skillName}.md`),
+				path: join(skillDir, "SKILL.md"),
 				content: getAiArtifactContent("claude", "skill", {
 					profile,
 					skillName
 				}) + "\n",
 				mode: "replace",
-				label: `${assistant} command`
+				label: `${assistant} skill`
 			});
 		}
 		if (assistant === "codex") {
@@ -380,19 +816,44 @@ function getAiArtifacts(options = {}) {
 			});
 		}
 	}
+	if (scope === "project") artifacts.push({
+		kind: "markdown-guidelines",
+		path: join(cwd, ".pagesmith", "markdown-guidelines.md"),
+		content: renderMarkdownGuidelines() + "\n",
+		mode: "replace",
+		label: "markdown guidelines"
+	});
+	if (scope === "project" && assistants.includes("claude")) {
+		artifacts.push({
+			assistant: "claude",
+			kind: "update-docs",
+			path: join(cwd, ".claude", "skills", "update-docs", "SKILL.md"),
+			content: renderUpdateDocsSkill(profile) + "\n",
+			mode: "replace",
+			label: "claude update-docs skill"
+		});
+		artifacts.push({
+			assistant: "claude",
+			kind: "update-all-docs",
+			path: join(cwd, ".claude", "skills", "ps-update-all-docs", "SKILL.md"),
+			content: renderUpdateAllDocsSkill(profile) + "\n",
+			mode: "replace",
+			label: "claude ps-update-all-docs skill"
+		});
+	}
 	if (shouldIncludeLlms(options)) {
 		const llmsDir = scope === "project" ? cwd : join(home, ".pagesmith");
 		artifacts.push({
 			kind: "llms",
 			path: join(llmsDir, "llms.txt"),
-			content: withManagedBlock("shared-llms", getAiArtifactContent("shared", "llms", { profile })) + "\n",
+			content: withManagedBlock("shared-llms", renderLlmsTxt()) + "\n",
 			mode: "merge",
 			label: "llms.txt"
 		});
 		artifacts.push({
 			kind: "llms-full",
 			path: join(llmsDir, "llms-full.txt"),
-			content: withManagedBlock("shared-llms-full", getAiArtifactContent("shared", "llms-full", { profile })) + "\n",
+			content: withManagedBlock("shared-llms-full", renderLlmsFullTxt()) + "\n",
 			mode: "merge",
 			label: "llms-full.txt"
 		});
@@ -400,7 +861,15 @@ function getAiArtifacts(options = {}) {
 	return artifacts;
 }
 function installAiArtifacts(options = {}) {
-	return getAiArtifacts(options).map((artifact) => ({
+	const artifacts = getAiArtifacts(options);
+	if (options.dryRun) return artifacts.map((artifact) => ({
+		assistant: artifact.assistant,
+		kind: artifact.kind,
+		path: artifact.path,
+		label: artifact.label,
+		status: "unchanged"
+	}));
+	return artifacts.map((artifact) => ({
 		assistant: artifact.assistant,
 		kind: artifact.kind,
 		path: artifact.path,