meowpress 0.3.0-alpha.2 → 0.3.0-alpha.3

package/README.md

@@ -1,30 +1,75 @@
 # Meowpress
 
-`meowpress` provides content reading, page rendering, themes and the build pipeline for static sites.
-Consumers own the site configuration and content and build through this package; the package does not own the application's posts or output directory.
+Meowpress builds a static blog from Markdown and MDX, with a built-in theme for posts, short notes
+and public skills. A project can supply its own theme or page map through `meowpress/build`.
 
-Published history: `0.1.1-alpha.0` was accepted from the registry, followed by `0.1.1-alpha.1` with the English site and CLI defaults; `latest` remained `0.1.0`. The current workspace package is `0.2.0-alpha.0`, and its required CSS and JSX peer ranges accept `^0.2.0-alpha.0`. The host selects the shared CSS/JSX modules, and this package does not privately install another CSS copy; it does not depend on Meowtail or MeowSlides. Out-of-package builds and theme identity acceptance are bound to exact package archives, and peer contracts are not bypassed through overrides. Publishing requires separate explicit authorization.
+## Build and preview a site
 
-This package is a standalone content publishing library with source in `packages/meowpress`; it already has a public build entry, independent tests and typechecking,
-and does not depend on Assistant, WorkCell, Deno or the content and runtime state of a specific Blog. Style generation comes from `meowcss`,
-and HTML rendering comes from `meowjsx/web`; MeowUI does not need to be installed.
+Use Bun and install this version of `meowpress` with compatible `meowcss` and `meowjsx` peers.
+When trying a workspace build, install the archives from `bun run build` and `bun run pack` in your
+project. From that project, add your first post and build the site.
 
-## Entries
+```sh
+mkdir -p content/posts
+printf '# First post\n\nHello from Meowpress.\n' > content/posts/first.md
+bunx --no-install meowpress build
+```
+
+Meowpress builds `dist/index.html` and `dist/posts/first/index.html`. Put short notes in
+`content/thoughts/` and public skills in `skills/<name>/SKILL.md`. `llms.txt` and `agents.md`
+describe the generated site. The default theme includes `404.html` for static hosts that serve a
+custom error page.
+
+Run `bunx --no-install meowpress preview` to serve the built files at `http://127.0.0.1:4173`.
+Run the build again after editing content. Deploy the `dist/` directory to a static host.
+
+## Configure an existing repository
 
-- `meowpress/build`: `meowSite()` defines configuration and `buildSite()` performs the build; this is the only public export.
-  Content reading, page rendering, skill indexing and themes are internal package modules.
-- `meowpress --config ./site.config.ts`: Bun CLI that loads the consumer-provided configuration and builds.
+Place `meowpress.config.ts` in the project root when your content lives outside the default
+folders or when you want to change the site name. This example uses `blog/` for posts, `notes/`
+for short notes and `blog/assets/images/` for the homepage image.
 
 ```ts
 import { meowSite } from "meowpress/build";
 
 export default meowSite({
-  content: [{ directory: "/path/to/content" }],
-  skillsDirectory: "/path/to/workspace",
-  outputDirectory: "/path/to/dist",
+  content: {
+    directory: ".",
+    postsDirectory: "blog",
+    thoughtsDirectory: "notes",
+    assetsDirectory: "blog/assets",
+  },
+  site: {
+    name: "My site",
+    images: { hero: "images/cover.svg" },
+  },
 });
 ```
 
+The directory names in `content` are relative to its `directory`. Posts from `blog/` still have
+URLs under `/posts/`, and notes still have URLs under `/thoughts/`. Meowpress copies `posts/assets/`
+to `/posts/assets/`. Set `postAssetsDirectory` to change the source of those files. Posts and assets
+whose paths contain a file or folder name starting with `_` are treated as drafts.
+
+Pass a project path after `build` or `preview` to run from another directory. The project root
+defaults to the current directory and is the base for relative config paths and output.
+The CLI looks for `meowpress.config.ts`, then `site.config.ts`. Use `--config <file>` to choose a
+file explicitly. `meowpress` and `meowpress --config ./site.config.ts` also build, and `preview`
+accepts `--port <port>`.
+
+Builds replace the generated output after they succeed. Meowpress reuses a nonempty default
+`dist/` only when it contains the previous build's `agents.md` and `llms.txt`. If another tool
+owns `dist/`, set `outputDirectory` to a separate directory and reserve it for generated files.
+
+`includeProjectSkills: true` opts in to publishing `.agents/skills/`. Set `projectRootDirectory`
+to choose the root for those skills. Set `notFound: false` to omit the built-in `404.html`, or
+supply `notFound: { title, message, homeLabel }` to change its copy.
+
+## Build from code
+
+`meowSite()` resolves configuration and `buildSite()` writes the site. Both are exported from
+`meowpress/build`. Use trusted local configuration and MDX, which execute code during a build.
+
 ## Pages a consumer owns
 
 A consumer that supplies `pages` owns the whole site map. The provider receives the content that was
@@ -64,7 +109,6 @@ export default meowSite({
   applies to the built-in pages as well, so a renamed stylesheet never leaves a page linking a file
   that was not written.
 
-Directories in the configuration are provided explicitly by the application; the default theme resolves from this package and does not depend on the startup directory.
 The whole theme can be replaced with `theme: defineTheme(...)`; all static pages output that theme's root attributes and default options.
 The build writes `theme.cssText` to a temporary CSS file, then lets Bun handle the other assets, and finally delivers through a stylesheet link,
 so the theme applies without client-side JavaScript.
@@ -80,19 +124,8 @@ Install the listed packages in the site; nothing depends on an external font ser
 Default illustrations use in-package vectors and CSS and require no business images. The `hero`, `feed` and `about` keys of `site.images`
 can explicitly set decorative image paths, for example `images/cover.svg`; paths are relative to the content root's `assets/`, the library handles each page depth,
 and assets are delivered along the existing asset build flow. When no About image is set, the first letter of the site name is used.
-The content source contains `posts/`, `thoughts/` and optional assets; drafts whose names start with an underscore do not enter the published output.
-The site has its own theme and does not implicitly install MeowUI's application theme.
-
-## Verification and build
-
-After installing `meowpress` and its `meowcss` and `meowjsx` dependencies, run in the consumer directory:
-
-```sh
-bunx --no-install meowpress --config ./site.config.ts
-```
-
-The CLI requires Bun, and the output location is determined by `outputDirectory`. Font packages resolve from the startup directory first, then from
-this package, which carries the default Geist, so consumers are not required to copy source, install workspace-root dependencies or access an external font service.
+Font packages resolve from the project root first, then from this package, which carries the
+default Geist.
 
 ## Independent verification
 

package/dist/src/build.d.ts

@@ -1,28 +1,32 @@
 import { type ThemeDefinition } from "meowcss";
 import { type SiteFont } from "./fonts.js";
-import { type SiteIdentity } from "./identity.js";
+import { type SiteIdentity, type SiteNotFound } from "./identity.js";
 import { type ContentSourceInput, type MdxComponent } from "./content.js";
 import { type SitePageProvider } from "./pages.js";
 export { sitePageMarkdownFile } from "./pages.js";
 export type { SitePage, SitePageContext, SitePageProvider } from "./pages.js";
-export type { ContentItem } from "./content.js";
+export type { ContentItem, ContentSource, ContentSourceInput } from "./content.js";
 export type { SiteFont } from "./fonts.js";
-export type { SiteIdentity } from "./identity.js";
+export type { SiteIdentity, SiteNotFound } from "./identity.js";
 export interface SiteConfig {
-    /** One or more roots containing `posts/`, `thoughts/`, and optional assets. */
-    content: ContentSourceInput | readonly ContentSourceInput[];
-    /** Workspace root used to discover public `skills/` and project `.agents/skills/`. */
-    skillsDirectory: string;
-    /** Static output directory for the generated site. */
-    outputDirectory: string;
+    /** Roots containing posts, thoughts and optional assets. Defaults to `content/`. */
+    content?: ContentSourceInput | readonly ContentSourceInput[];
+    /** Root used to discover public `skills/`. Defaults to the current project directory. */
+    skillsDirectory?: string;
+    /** Static output directory for the generated site. Defaults to `dist/`. */
+    outputDirectory?: string;
     /** Defaults to this package's own Blog theme. */
     theme?: ThemeDefinition;
-    /** Optional project root when project Skills live outside `skillsDirectory`. */
+    /** Include project `.agents/skills/` in the public build. Defaults to false. */
+    includeProjectSkills?: boolean;
+    /** Alternate root for `.agents/skills/` when `includeProjectSkills` is enabled. */
     projectRootDirectory?: string;
     /** Site name, description, repository links and About copy; unset fields use neutral defaults. */
     site?: Partial<SiteIdentity>;
-    /** Consumer-supplied pages; the site writes and indexes them next to its own. */
+    /** Consumer-supplied pages replace the built-in site map. */
     pages?: SitePageProvider;
+    /** Copy for the built-in root `404.html`, or false to omit it. */
+    notFound?: SiteNotFound | false;
     /**
      * Markdown that opens `llms.txt` and `llms-full.txt` after the site summary: what an agent must
      * know before following any link, such as how to install and set up what the site documents.
@@ -43,14 +47,16 @@ export interface ResolvedSiteConfig {
     skillsDirectory: string;
     outputDirectory: string;
     theme: ThemeDefinition;
+    includeProjectSkills?: boolean;
     projectRootDirectory?: string;
     site: SiteIdentity;
     pages?: SitePageProvider;
+    notFound?: SiteNotFound | false;
     agentGuide?: string;
     mdxComponents: Record<string, MdxComponent>;
     themeStylesheet: string;
     fonts: readonly SiteFont[];
 }
 /** Define a site config in the app package without taking on the build pipeline. */
-export declare function meowSite(config: SiteConfig): ResolvedSiteConfig;
-export declare function buildSite(input: SiteConfig | ResolvedSiteConfig): Promise<void>;
+export declare function meowSite(config?: SiteConfig): ResolvedSiteConfig;
+export declare function buildSite(input?: SiteConfig | ResolvedSiteConfig): Promise<void>;

package/dist/src/build.js

@@ -2,28 +2,35 @@ import { removeLegacyIsFallbacks } from "meowcss/bundle";
 import { blogFonts, blogTheme } from "./theme.js";
 import { FONT_EXTERNAL, publishFonts } from "./fonts.js";
 import { DEFAULT_SITE } from "./identity.js";
-import { mkdir, readFile, rm, writeFile, cp } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { constants } from "node:fs";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { collectContentAssets, isDraftAsset, loadSection, normalizeContentSources, } from "./content.js";
-import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmFullText, llmText, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
+import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmFullText, llmText, notFoundPage, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
 import { loadSkills } from "./skills.js";
 import { sitePageFile, sitePageMarkdownFile } from "./pages.js";
+import { publishSite, validateBuildDestination, validateOutputDirectory } from "./output.js";
 export { sitePageMarkdownFile } from "./pages.js";
 /** Define a site config in the app package without taking on the build pipeline. */
-export function meowSite(config) {
+export function meowSite(config = {}) {
+    const themeStylesheet = config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET;
+    if (basename(themeStylesheet) !== themeStylesheet || !themeStylesheet.endsWith(".css"))
+        throw new Error(`Expected a theme stylesheet file name: ${themeStylesheet}`);
     return {
-        content: normalizeContentSources(config.content),
-        skillsDirectory: resolve(config.skillsDirectory),
-        outputDirectory: resolve(config.outputDirectory),
+        content: normalizeContentSources(config.content ?? "content"),
+        skillsDirectory: resolve(config.skillsDirectory ?? "."),
+        outputDirectory: resolve(config.outputDirectory ?? "dist"),
         theme: config.theme ?? blogTheme,
+        includeProjectSkills: config.includeProjectSkills,
         projectRootDirectory: config.projectRootDirectory
             ? resolve(config.projectRootDirectory)
             : undefined,
         site: { ...DEFAULT_SITE, ...config.site },
         pages: config.pages,
+        notFound: config.notFound,
         agentGuide: config.agentGuide,
         mdxComponents: config.mdxComponents ?? {},
-        themeStylesheet: config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET,
+        themeStylesheet,
         fonts: config.fonts ?? (config.theme === undefined || config.theme === blogTheme ? blogFonts : []),
     };
 }
@@ -33,25 +40,23 @@ async function writePage(generatedDirectory, pathname, html) {
     await writeFile(target, html, "utf8");
     return target;
 }
-async function stageAssets(generatedDirectory, sources) {
-    const assets = await collectContentAssets(sources, { directory: "assets" });
-    await Promise.all(assets
-        .filter((asset) => !isDraftAsset(asset.sourcePath, asset.assetRoot))
-        .map(async (asset) => {
-        const target = join(generatedDirectory, asset.relativePath);
-        await mkdir(resolve(target, ".."), { recursive: true });
-        await cp(asset.sourcePath, target, { force: true });
-    }));
-}
-async function copyPostAssets(outputDirectory, sources) {
-    const assets = await collectContentAssets(sources, { directory: "posts/assets" });
-    await Promise.all(assets
-        .filter((asset) => !isDraftAsset(asset.sourcePath, asset.assetRoot))
-        .map(async (asset) => {
-        const target = join(outputDirectory, "posts/assets", asset.relativePath);
-        await mkdir(resolve(target, ".."), { recursive: true });
-        await cp(asset.sourcePath, target, { force: true });
-    }));
+async function writeAssets(destination, sources, directory) {
+    const assets = await collectContentAssets(sources, { directory });
+    for (const asset of assets) {
+        if (isDraftAsset(asset.sourcePath, asset.assetRoot))
+            continue;
+        const path = directory === "assets" ? asset.relativePath : join(directory, asset.relativePath);
+        const target = join(destination, path);
+        await mkdir(dirname(target), { recursive: true });
+        try {
+            await copyFile(asset.sourcePath, target, constants.COPYFILE_EXCL);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            throw new Error(`Content asset would replace a generated file: ${path}`);
+        }
+    }
 }
 async function buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, outputDirectory) {
     const result = await Bun.build({
@@ -60,13 +65,12 @@ async function buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, o
         outdir: outputDirectory,
         target: "browser",
         minify: true,
+        throw: false,
         // Published font files stay separate, so subsets load by unicode-range instead of inline.
         external: [FONT_EXTERNAL],
     });
-    if (!result.success) {
-        console.error(result.logs);
-        throw new Error("Unable to build site static HTML");
-    }
+    if (!result.success)
+        throw new Error(["Unable to build site static HTML", ...result.logs.map((log) => log.message)].join("\n"));
     // Bun writes legacy :-webkit-any()/:-moz-any() copies of every :is() rule; Safari misreads them.
     for (const output of result.outputs)
         if (output.path.endsWith(".css"))
@@ -111,21 +115,36 @@ async function writeContentPages(generatedDirectory, posts, thoughts, theme, sit
     }
     return entrypoints;
 }
-export async function buildSite(input) {
+export async function buildSite(input = {}) {
     const config = meowSite(input);
-    const generatedDirectory = resolve(config.outputDirectory, "../.generated");
+    await validateOutputDirectory(config);
+    await validateBuildDestination(config.outputDirectory);
+    const outputParent = dirname(config.outputDirectory);
+    await mkdir(outputParent, { recursive: true });
+    const workspace = await mkdtemp(join(outputParent, ".meowpress-build-"));
+    try {
+        const outputDirectory = join(workspace, "output");
+        const result = await writeSite({ ...config, outputDirectory }, join(workspace, "source"));
+        await validateBuildDestination(config.outputDirectory);
+        await publishSite(outputDirectory, config.outputDirectory);
+        console.log(`Built ${result} into ${config.outputDirectory}.`);
+    }
+    finally {
+        await rm(workspace, { recursive: true, force: true });
+    }
+}
+async function writeSite(config, generatedDirectory) {
     const [posts, thoughts, skills] = await Promise.all([
         loadSection(config.content, "post", { components: config.mdxComponents }),
         loadSection(config.content, "thought", { components: config.mdxComponents }),
         config.pages
             ? Promise.resolve([])
             : loadSkills(config.skillsDirectory, {
+                includeProjectSkills: config.includeProjectSkills,
                 projectRootDirectory: config.projectRootDirectory,
             }),
     ]);
     const timeline = [...posts, ...thoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0));
-    await rm(config.outputDirectory, { recursive: true, force: true });
-    await rm(generatedDirectory, { recursive: true, force: true });
     await mkdir(config.outputDirectory, { recursive: true });
     await mkdir(generatedDirectory, { recursive: true });
     // A consumer that supplies its own pages owns the whole site map; the package's
@@ -150,6 +169,9 @@ export async function buildSite(input) {
             writePage(generatedDirectory, "thoughts/index.html", listPage("thought", thoughts, config.theme, config.site, config.themeStylesheet)),
             writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site, config.themeStylesheet)),
         ])), ...(await writeContentPages(generatedDirectory, posts, thoughts, config.theme, config.site, config.themeStylesheet)));
+        if (config.notFound !== false) {
+            entrypoints.push(await writePage(generatedDirectory, "404.html", notFoundPage(config.notFound ?? {}, config.theme, config.site, config.themeStylesheet)));
+        }
         for (const skill of skills) {
             const skillPath = skill.scope === "public" ? `skills/${skill.slug}` : `skills/project/${skill.slug}`;
             entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site, config.themeStylesheet)));
@@ -159,11 +181,11 @@ export async function buildSite(input) {
     // root, next to the published font directory its rules reference.
     const fontFaces = await publishFonts(config.fonts, config.outputDirectory);
     await writeFile(join(generatedDirectory, config.themeStylesheet), fontFaces ? `${fontFaces}\n${config.theme.cssText}` : config.theme.cssText, "utf8");
-    await stageAssets(generatedDirectory, config.content);
+    await writeAssets(generatedDirectory, config.content, "assets");
     await buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, config.outputDirectory);
-    await copyPostAssets(config.outputDirectory, config.content);
     if (pages)
         await writeConsumerMarkdown(config.outputDirectory, pages);
+    await writeAssets(config.outputDirectory, config.content, "posts/assets");
     const full = pages ? llmFullText(config.site, pages, config.agentGuide) : undefined;
     await Promise.all([
         writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site, pages, config.agentGuide), "utf8"),
@@ -171,10 +193,10 @@ export async function buildSite(input) {
         ...(full === undefined
             ? []
             : [writeFile(join(config.outputDirectory, "llms-full.txt"), full, "utf8")]),
-        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages), "utf8"),
+        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages, config.content.some((source) => typeof source !== "string" &&
+            (source.postsDirectory !== undefined || source.thoughtsDirectory !== undefined))), "utf8"),
     ]);
-    await rm(generatedDirectory, { recursive: true, force: true });
-    console.log(pages
-        ? `Built ${posts.length} content items and ${pages.length} site pages into site dist/.`
-        : `Built ${posts.length} posts and ${thoughts.length} thoughts into site dist/.`);
+    return pages
+        ? `${posts.length} content items and ${pages.length} site pages`
+        : `${posts.length} posts and ${thoughts.length} thoughts`;
 }

package/dist/src/cli.js

@@ -1,22 +1,113 @@
 #!/usr/bin/env bun
+import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { buildSite } from "./build.js";
-function configPathFromArgs(args) {
-    const index = args.indexOf("--config");
-    const configPath = index >= 0 ? args[index + 1] : undefined;
-    if (!configPath || configPath.startsWith("--")) {
-        throw new Error("Usage: meowpress --config <site-config.ts>");
+import { buildSite, meowSite } from "./build.js";
+import { hasBuiltSite, validateOutputDirectory } from "./output.js";
+import { serveSite } from "./preview.js";
+const USAGE = [
+    "Usage: meowpress [--config <file>]",
+    "       meowpress build [root] [--config <file>]",
+    "       meowpress preview [root] [--config <file>] [--port <port>]",
+].join("\n");
+const CONFIG_FILES = ["meowpress.config.ts", "site.config.ts"];
+function parseArgs(args) {
+    const command = args[0] === "preview" ? "preview" : "build";
+    const hasCommand = args[0] === command;
+    let root;
+    let config;
+    let port;
+    for (let index = hasCommand ? 1 : 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--config" && config === undefined) {
+            const value = args[++index];
+            if (!value || value.startsWith("-"))
+                throw new Error("Missing file for --config");
+            config = value;
+        }
+        else if (arg === "--port" && command === "preview" && port === undefined) {
+            const value = args[++index];
+            port = Number(value);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                throw new Error("Port must be an integer between 1 and 65535");
+        }
+        else if (hasCommand && !arg.startsWith("-") && root === undefined) {
+            root = arg;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${arg}\n${USAGE}`);
+        }
     }
-    return resolve(process.cwd(), configPath);
+    return { command, root: resolve(root ?? "."), config, port };
+}
+async function loadConfig(config) {
+    for (const candidate of config === undefined ? CONFIG_FILES : [config]) {
+        const configPath = resolve(candidate);
+        try {
+            if (!(await stat(configPath)).isFile())
+                throw new Error(`Site config is not a file: ${configPath}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (config !== undefined)
+                throw new Error(`Site config not found: ${configPath}`);
+            continue;
+        }
+        const module = (await import(pathToFileURL(configPath).href));
+        const site = module.default ?? module.site;
+        if (typeof site !== "object" || site === null || Array.isArray(site))
+            throw new Error(`Expected a default site config object or a named site export in ${configPath}`);
+        return site;
+    }
+    return {};
 }
 export async function runSiteCli(args = Bun.argv.slice(2)) {
-    const configPath = configPathFromArgs(args);
-    const module = (await import(pathToFileURL(configPath).href));
-    const config = module.default ?? module.site;
-    if (!config)
-        throw new Error(`No default site config exported from ${configPath}`);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+    const options = parseArgs(args);
+    if (options.root !== process.cwd()) {
+        if (!(await stat(options.root).catch(() => undefined))?.isDirectory())
+            throw new Error(`Project root is not a directory: ${options.root}`);
+        // Trusted config can call meowSite while loading, so it and its imports need the selected cwd.
+        const child = Bun.spawn([
+            process.execPath,
+            import.meta.path,
+            options.command,
+            ...(options.config ? ["--config", options.config] : []),
+            ...(options.port ? ["--port", String(options.port)] : []),
+        ], { cwd: options.root, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+        const interrupt = () => child.kill("SIGINT");
+        const terminate = () => child.kill("SIGTERM");
+        process.once("SIGINT", interrupt);
+        process.once("SIGTERM", terminate);
+        try {
+            process.exitCode = await child.exited;
+        }
+        finally {
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", terminate);
+        }
+        return;
+    }
+    const config = await loadConfig(options.config);
+    if (options.command === "preview") {
+        const resolved = meowSite(config);
+        await validateOutputDirectory(resolved);
+        if (!(await hasBuiltSite(resolved.outputDirectory))) {
+            throw new Error(`Built site not found at ${resolved.outputDirectory}. Run meowpress build first.`);
+        }
+        const server = await serveSite(resolved.outputDirectory, options.port);
+        console.log(`Meowpress preview: ${server.url}`);
+        return;
+    }
     await buildSite(config);
 }
-if (import.meta.main)
-    await runSiteCli();
+if (import.meta.main) {
+    await runSiteCli().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}

package/dist/src/content.d.ts

@@ -4,6 +4,14 @@ export type Frontmatter = Record<string, unknown>;
 /** A content root containing `posts/`, `thoughts/`, and optional asset folders. */
 export interface ContentSource {
     directory: string;
+    /** Markdown and MDX posts, relative to the source root. Defaults to "posts". */
+    postsDirectory?: string;
+    /** Markdown and MDX thoughts, relative to the source root. Defaults to "thoughts". */
+    thoughtsDirectory?: string;
+    /** Assets for site pages and styles, relative to the source root. Defaults to "assets". */
+    assetsDirectory?: string;
+    /** Assets copied to /posts/assets/, relative to the source root. Defaults to "posts/assets". */
+    postAssetsDirectory?: string;
     /** Namespace slugs and asset paths from this source to avoid collisions. */
     slugPrefix?: string;
 }
@@ -47,7 +55,7 @@ export interface CollectContentAssetsOptions {
     directory?: string;
     duplicate?: DuplicateContentPolicy;
 }
-export declare function normalizeContentSources(input: ContentSourceInput | readonly ContentSourceInput[]): ContentSource[];
+export declare function normalizeContentSources(input: ContentSourceInput | readonly ContentSourceInput[], baseDirectory?: string): ContentSource[];
 export declare function loadSection(sources: ContentSourceInput | readonly ContentSourceInput[], kind: ContentKind, options?: LoadSectionOptions): Promise<ContentItem[]>;
 export declare function withoutLeadingHeading(html: string): string;
 export declare function collectAssetFiles(directory: string): Promise<string[]>;

package/dist/src/content.js

@@ -1,7 +1,7 @@
 import { compile, run } from "@mdx-js/mdx";
 import remarkGfm from "remark-gfm";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { relative, resolve, sep } from "node:path";
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { Fragment, h } from "meowjsx/runtime";
 import { renderToHtml } from "meowjsx/web";
@@ -42,16 +42,24 @@ function parseDate(value) {
 function makeDateKey(value, date) {
     const text = asText(value);
     const explicitDate = text?.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
-    if (explicitDate)
-        return explicitDate;
+    if (explicitDate) {
+        const parsed = new Date(`${explicitDate}T00:00:00Z`);
+        if (!Number.isNaN(parsed.getTime()) && parsed.toISOString().startsWith(explicitDate)) {
+            return explicitDate;
+        }
+    }
     if (!date)
         return "undated";
-    return new Intl.DateTimeFormat("en-CA", {
+    const parts = new Intl.DateTimeFormat("en-US", {
         timeZone: "Asia/Shanghai",
         year: "numeric",
         month: "2-digit",
         day: "2-digit",
-    }).format(date);
+    }).formatToParts(date);
+    const year = parts.find((part) => part.type === "year").value;
+    const month = parts.find((part) => part.type === "month").value;
+    const day = parts.find((part) => part.type === "day").value;
+    return `${year.padStart(4, "0")}-${month}-${day}`;
 }
 function makeTimeLabel(value, date) {
     const text = asText(value);
@@ -126,14 +134,14 @@ async function renderMdx(source, components) {
     return renderToHtml(component({ components: { ...MDX_COMPONENTS, ...components } }));
 }
 async function renderSource(source, sourcePath, components) {
-    if (sourcePath.endsWith(".md")) {
+    if (sourcePath.toLowerCase().endsWith(".md")) {
         return Bun.markdown.html(source, {
             tagFilter: true,
         });
     }
     return renderMdx(source, components);
 }
-async function collectFiles(directory) {
+async function collectFiles(directory, assetRoots, skipNestedAssets) {
     const entries = await readdir(directory, { withFileTypes: true });
     const files = [];
     for (const entry of entries) {
@@ -141,10 +149,13 @@ async function collectFiles(directory) {
             continue;
         const entryPath = resolve(directory, entry.name);
         if (entry.isDirectory()) {
-            files.push(...(await collectFiles(entryPath)));
+            if (assetRoots.has(entryPath) || (skipNestedAssets && entry.name === "assets"))
+                continue;
+            files.push(...(await collectFiles(entryPath, assetRoots, skipNestedAssets)));
             continue;
         }
-        if (CONTENT_EXTENSIONS.has(entry.name.slice(entry.name.lastIndexOf(".")))) {
+        const extension = entry.name.slice(entry.name.lastIndexOf(".")).toLowerCase();
+        if (entry.isFile() && CONTENT_EXTENSIONS.has(extension)) {
             files.push(entryPath);
         }
     }
@@ -164,39 +175,90 @@ function makeSlug(sourcePath, sectionDirectory) {
         .join("/");
 }
 function normalizeSlugPrefix(prefix) {
-    return (prefix ?? "")
+    const normalized = (prefix ?? "")
         .replaceAll("\\", "/")
         .replace(/^\/+|\/+$/g, "")
         .replaceAll(/\/+/g, "/");
+    if (normalized.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`Content slug prefix must not contain "." or "..": ${prefix}`);
+    }
+    return normalized;
 }
 function withSlugPrefix(prefix, slug) {
     const normalizedPrefix = normalizeSlugPrefix(prefix);
     return normalizedPrefix ? `${normalizedPrefix}/${slug}` : slug;
 }
-export function normalizeContentSources(input) {
+export function normalizeContentSources(input, baseDirectory = process.cwd()) {
     const sources = Array.isArray(input) ? input : [input];
     return sources.map((source) => {
         const normalized = typeof source === "string" ? { directory: source } : source;
+        const directory = resolve(baseDirectory, normalized.directory);
+        for (const mapping of [
+            normalized.postsDirectory,
+            normalized.thoughtsDirectory,
+            normalized.assetsDirectory,
+            normalized.postAssetsDirectory,
+        ]) {
+            if (mapping !== undefined)
+                sourceDirectory(directory, mapping);
+        }
         return {
-            directory: resolve(normalized.directory),
+            ...normalized,
+            directory,
             slugPrefix: normalizeSlugPrefix(normalized.slugPrefix) || undefined,
         };
     });
 }
-function duplicateContentError(kind, slug) {
-    return new Error(`Duplicate ${kind} slug "${slug}" while merging content sources.`);
+function sourceDirectory(root, path) {
+    const target = resolve(root, path);
+    const local = relative(root, target);
+    if (isAbsolute(path) || local === ".." || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+        throw new Error(`Content directory must stay inside its source root: ${path}`);
+    }
+    return target;
 }
-async function loadSectionFromSource(source, kind, options) {
-    const sectionDirectory = resolve(source.directory, `${kind}s`);
-    let sourceFiles;
+/** Check every segment below a source root before walking a configured directory. */
+async function isSourceDirectory(root, target) {
     try {
-        sourceFiles = await collectFiles(sectionDirectory);
+        let path = root;
+        if (!(await lstat(path)).isDirectory())
+            return false;
+        for (const segment of relative(root, target).split(sep).filter(Boolean)) {
+            path = resolve(path, segment);
+            if (!(await lstat(path)).isDirectory())
+                return false;
+        }
+        return true;
     }
     catch (error) {
         if (error.code === "ENOENT")
-            return [];
+            return false;
         throw error;
     }
+}
+function assetDirectory(source, directory) {
+    const mapping = directory === "assets"
+        ? source.assetsDirectory
+        : directory === "posts/assets"
+            ? source.postAssetsDirectory
+            : undefined;
+    return sourceDirectory(source.directory, mapping ?? directory);
+}
+function duplicateContentError(kind, slug) {
+    return new Error(`Duplicate ${kind} slug "${slug}" while merging content sources.`);
+}
+async function loadSectionFromSource(source, kind, options) {
+    const mapping = kind === "post" ? source.postsDirectory : source.thoughtsDirectory;
+    const sectionDirectory = sourceDirectory(source.directory, mapping ?? `${kind}s`);
+    if (!(await isSourceDirectory(source.directory, sectionDirectory)))
+        return [];
+    const assetRoots = new Set([
+        assetDirectory(source, "assets"),
+        assetDirectory(source, "posts/assets"),
+    ]);
+    if (assetRoots.has(sectionDirectory))
+        return [];
+    const sourceFiles = await collectFiles(sectionDirectory, assetRoots, mapping !== undefined);
     const items = [];
     for (const sourcePath of sourceFiles) {
         if (isDraft(sourcePath, sectionDirectory, kind))
@@ -278,7 +340,7 @@ async function collectFilesForAssets(directory) {
         if (entry.isDirectory()) {
             files.push(...(await collectFilesForAssets(entryPath)));
         }
-        else {
+        else if (entry.isFile()) {
             files.push(entryPath);
         }
     }
@@ -289,7 +351,9 @@ export async function collectContentAssets(sources, options = {}) {
     const duplicatePolicy = options.duplicate ?? "first-wins";
     const assets = new Map();
     for (const source of normalizeContentSources(sources)) {
-        const assetRoot = resolve(source.directory, directory);
+        const assetRoot = assetDirectory(source, directory);
+        if (!(await isSourceDirectory(source.directory, assetRoot)))
+            continue;
         const sourceFiles = await collectAssetFiles(assetRoot);
         for (const sourcePath of sourceFiles) {
             const localPath = relative(assetRoot, sourcePath).split(sep).join("/");

package/dist/src/identity.d.ts

@@ -14,6 +14,12 @@ export interface SiteAbout {
     linksHeading?: string;
     links?: readonly SiteProfileLink[];
 }
+/** Optional copy for the built-in 404 page. */
+export interface SiteNotFound {
+    title?: string;
+    message?: string;
+    homeLabel?: string;
+}
 /** Site-owned identity and copy. The application supplies it; the library keeps neutral defaults. */
 export interface SiteIdentity {
     /** Display name used in header, footer and document titles. */

package/dist/src/output.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedSiteConfig } from "./build.js";
+export declare function validateOutputDirectory(config: ResolvedSiteConfig): Promise<void>;
+/** Both agent indexes have been emitted by Meowpress since before the conventional CLI. */
+export declare function hasBuiltSite(directory: string): Promise<boolean>;
+export declare function validateBuildDestination(directory: string): Promise<void>;
+/** Move a complete build into place and preserve any previous build if that move fails. */
+export declare function publishSite(staged: string, destination: string): Promise<void>;

package/dist/src/output.js

@@ -0,0 +1,111 @@
+import { lstat, mkdtemp, readdir, realpath, rename, rm } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { normalizeContentSources } from "./content.js";
+function isMissing(error) {
+    return error.code === "ENOENT";
+}
+async function existingPath(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return undefined;
+    }
+}
+/** Resolve symlinked ancestors even if the output directory has not been created yet. */
+async function filesystemPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return join(await filesystemPath(dirname(path)), basename(path));
+    }
+}
+function containsPath(directory, path) {
+    const fromDirectory = relative(directory, path);
+    return (!isAbsolute(fromDirectory) && fromDirectory !== ".." && !fromDirectory.startsWith(`..${sep}`));
+}
+export async function validateOutputDirectory(config) {
+    const project = process.cwd();
+    const sources = normalizeContentSources(config.content);
+    const sourceRoots = [
+        project,
+        config.skillsDirectory,
+        ...sources.map((source) => source.directory),
+    ];
+    if (config.projectRootDirectory)
+        sourceRoots.push(config.projectRootDirectory);
+    const inputs = sources.flatMap((source) => [
+        resolve(source.directory, source.postsDirectory ?? "posts"),
+        resolve(source.directory, source.thoughtsDirectory ?? "thoughts"),
+        resolve(source.directory, source.assetsDirectory ?? "assets"),
+        resolve(source.directory, source.postAssetsDirectory ?? "posts/assets"),
+    ]);
+    inputs.push(join(config.skillsDirectory, "skills"), join(project, ".agents"), join(project, ".git"));
+    if (config.includeProjectSkills)
+        inputs.push(join(config.projectRootDirectory ?? config.skillsDirectory, ".agents/skills"));
+    const [output, roots, directories] = await Promise.all([
+        filesystemPath(config.outputDirectory),
+        Promise.all(sourceRoots.map(filesystemPath)),
+        Promise.all(inputs.map(filesystemPath)),
+    ]);
+    if (roots.some((root) => containsPath(output, root)) ||
+        directories.some((input) => containsPath(output, input) || containsPath(input, output))) {
+        throw new Error(`Output directory overlaps project files: ${config.outputDirectory}`);
+    }
+    const info = await existingPath(config.outputDirectory);
+    if (info && !info.isDirectory())
+        throw new Error(`Site output must be a directory: ${config.outputDirectory}`);
+}
+/** Both agent indexes have been emitted by Meowpress since before the conventional CLI. */
+export async function hasBuiltSite(directory) {
+    const markers = await Promise.all(["agents.md", "llms.txt"].map((name) => existingPath(join(directory, name))));
+    return markers.every((marker) => marker?.isFile());
+}
+export async function validateBuildDestination(directory) {
+    if (directory === resolve("dist") &&
+        (await existingPath(directory)) &&
+        (await readdir(directory)).length &&
+        !(await hasBuiltSite(directory))) {
+        throw new Error(`Refusing to replace existing files in ${directory}. Move them or choose another outputDirectory.`);
+    }
+}
+/** Move a complete build into place and preserve any previous build if that move fails. */
+export async function publishSite(staged, destination) {
+    const existing = await existingPath(destination);
+    if (!existing) {
+        await rename(staged, destination);
+        return;
+    }
+    if (!existing.isDirectory())
+        throw new Error(`Site output must be a directory: ${destination}`);
+    const backupDirectory = await mkdtemp(join(dirname(destination), ".meowpress-previous-"));
+    const backup = join(backupDirectory, basename(destination));
+    let restoreFailed = false;
+    try {
+        await rename(destination, backup);
+        try {
+            await rename(staged, destination);
+        }
+        catch (error) {
+            try {
+                await rename(backup, destination);
+            }
+            catch {
+                restoreFailed = true;
+                throw new Error(`Could not replace ${destination}. Previous output remains in ${backup}.`, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    finally {
+        if (!restoreFailed)
+            await rm(backupDirectory, { recursive: true, force: true });
+    }
+}

package/dist/src/preview.d.ts

@@ -0,0 +1 @@
+export declare function serveSite(outputDirectory: string, port?: number): Promise<Bun.Server<undefined>>;

package/dist/src/preview.js

@@ -0,0 +1,61 @@
+import { realpath, stat } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+async function statIfPresent(path) {
+    try {
+        return await stat(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return undefined;
+        throw error;
+    }
+}
+export async function serveSite(outputDirectory, port = 4173) {
+    if (!(await statIfPresent(outputDirectory))?.isDirectory()) {
+        throw new Error(`Built site not found at ${outputDirectory}. Run meowpress build first.`);
+    }
+    const root = await realpath(outputDirectory);
+    const isInside = (path) => path === root || path.startsWith(root + sep);
+    async function fileResponse(path, method, status) {
+        if (!(await statIfPresent(path))?.isFile())
+            return undefined;
+        const target = await realpath(path);
+        if (!isInside(target))
+            return undefined;
+        const file = Bun.file(target);
+        return new Response(method === "HEAD" ? null : file, {
+            status,
+            headers: { "Content-Type": file.type, "Cache-Control": "no-store" },
+        });
+    }
+    return Bun.serve({
+        hostname: "127.0.0.1",
+        port,
+        async fetch(request) {
+            if (request.method !== "GET" && request.method !== "HEAD")
+                return new Response("Method not allowed", { status: 405, headers: { Allow: "GET, HEAD" } });
+            const url = new URL(request.url);
+            let pathname;
+            try {
+                pathname = decodeURIComponent(url.pathname);
+            }
+            catch {
+                return new Response("Invalid path", { status: 400 });
+            }
+            if (pathname.includes("\0"))
+                return new Response("Invalid path", { status: 400 });
+            const target = resolve(root, `.${pathname}`);
+            if (!isInside(target))
+                return new Response("Forbidden", { status: 403 });
+            if (!pathname.endsWith("/") && (await statIfPresent(target))?.isDirectory()) {
+                url.pathname += "/";
+                return Response.redirect(url, 301);
+            }
+            const path = pathname.endsWith("/") ? join(target, "index.html") : target;
+            return ((await fileResponse(path, request.method, 200)) ??
+                (await fileResponse(join(root, "404.html"), request.method, 404)) ??
+                new Response(request.method === "HEAD" ? null : "Page not found", { status: 404 }));
+        },
+    });
+}

package/dist/src/site.d.ts

@@ -1,18 +1,19 @@
 import { type ThemeDefinition } from "meowcss";
 import { type ContentItem } from "./content.js";
-import { type SiteIdentity } from "./identity.js";
+import { type SiteIdentity, type SiteNotFound } from "./identity.js";
 import { type SitePage } from "./pages.js";
 import type { Skill } from "./skills.js";
 /** The name of the theme stylesheet the package writes by default. */
 export declare const DEFAULT_THEME_STYLESHEET = "blog-theme.css";
 export declare function homePage(items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
 export declare function listPage(kind: "post" | "thought", items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function notFoundPage(copy: SiteNotFound, theme: ThemeDefinition, site: SiteIdentity, stylesheet: string): string;
 export declare function postPage(item: ContentItem, posts: ContentItem[], thoughts: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
 export declare function thoughtPage(item: ContentItem, theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
 export declare function aboutPage(theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
 export declare function skillsIndexPage(skills: Skill[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
 export declare function skillPage(skill: Skill, theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
-export declare function agentMarkdown(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity, pages?: readonly SitePage[]): string;
+export declare function agentMarkdown(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity, pages?: readonly SitePage[], mappedSections?: boolean): string;
 export declare function llmText(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity, pages?: readonly SitePage[], agentGuide?: string): string;
 /**
  * Every page's Markdown in one file, after the same summary and guide as llms.txt. Pages without

package/dist/src/site.js

@@ -35,7 +35,7 @@ function SiteFooter({ site }) {
             " \u00B7 ",
             h("a", { href: "/agents.md" }, "agents.md"))));
 }
-function Document({ title, description, activePath, styleHref, children, theme, site, }) {
+function Document({ title, description, activePath, styleHref, baseHref, children, theme, site, }) {
     const documentTitle = title === site.name ? site.name : `${title} · ${site.name}`;
     return (h("html", { lang: "en", ...themeAttributes(theme) },
         h("head", null,
@@ -44,6 +44,7 @@ function Document({ title, description, activePath, styleHref, children, theme,
             h("meta", { name: "description", content: description ?? site.description }),
             h("meta", { name: "theme-color", media: "(prefers-color-scheme: light)", content: "#faf8f3" }),
             h("meta", { name: "theme-color", media: "(prefers-color-scheme: dark)", content: "#191816" }),
+            baseHref ? h("base", { href: baseHref }) : null,
             h("link", { rel: "stylesheet", href: styleHref }),
             h("title", null, documentTitle)),
         h("body", { "data-site": site.id },
@@ -56,20 +57,20 @@ function pageHtml(props) {
     return `<!doctype html>\n${renderToHtml(h(Document, { ...props }))}`;
 }
 function dateLabel(dateKey) {
-    if (dateKey === "undated")
+    const date = new Date(`${dateKey}T00:00:00Z`);
+    if (Number.isNaN(date.getTime()))
         return { date: "Undated", weekday: "" };
-    const date = new Date(`${dateKey}T00:00:00+08:00`);
+    const weekday = new Intl.DateTimeFormat("en-US", {
+        timeZone: "UTC",
+        weekday: "short",
+    }).format(date);
     return {
         date: new Intl.DateTimeFormat("en-US", {
-            timeZone: "Asia/Shanghai",
+            timeZone: "UTC",
             month: "long",
             day: "numeric",
         }).format(date),
-        weekday: new Intl.DateTimeFormat("en-US", {
-            timeZone: "Asia/Shanghai",
-            weekday: "short",
-            year: "numeric",
-        }).format(date),
+        weekday: `${date.getUTCFullYear()} ${weekday}`,
     };
 }
 function itemUrl(item) {
@@ -282,6 +283,26 @@ export function listPage(kind, items, theme = blogTheme, site = DEFAULT_SITE, st
             h("div", { className: isPost ? "post-list" : "thought-list" }, items.length === 0 ? (h("p", { className: "empty-state" }, "No public content yet.")) : (items.map((item) => isPost ? h(PostCard, { item: item }) : h(ThoughtCard, { item: item, linked: true })))))),
     });
 }
+export function notFoundPage(copy, theme, site, stylesheet) {
+    const title = copy.title ?? "Page not found";
+    const message = copy.message ?? "This page may have moved or been removed.";
+    return pageHtml({
+        site,
+        theme,
+        title,
+        description: message,
+        styleHref: styleHref(0, stylesheet),
+        // Static hosts can serve 404.html at the missing URL, including deep paths.
+        baseHref: "/",
+        children: (h("main", { className: "listing" },
+            h("header", { className: "listing-head" },
+                h("span", { className: "kind" }, "404"),
+                h("h1", null, title),
+                h("p", null, message)),
+            h("div", { className: "prose" },
+                h("a", { href: "/" }, copy.homeLabel ?? "Back to home")))),
+    });
+}
 function PostNavigation({ item, posts }) {
     const index = posts.findIndex((post) => post.slug === item.slug);
     const older = index >= 0 ? posts[index + 1] : undefined;
@@ -673,7 +694,7 @@ export function skillPage(skill, theme = blogTheme, site = DEFAULT_SITE, stylesh
             h("script", { dangerouslySetInnerHTML: { __html: SKILL_BROWSER_SCRIPT } }))),
     });
 }
-export function agentMarkdown(posts, thoughts, site = DEFAULT_SITE, pages) {
+export function agentMarkdown(posts, thoughts, site = DEFAULT_SITE, pages, mappedSections = false) {
     const siteMap = pages
         ? pages.map((page) => `- [${page.title}](${sitePageAgentUrl(page)})`)
         : [
@@ -694,8 +715,12 @@ export function agentMarkdown(posts, thoughts, site = DEFAULT_SITE, pages) {
         "",
         "## Content model",
         "",
-        `- \`${site.contentDirectory}/thoughts/\` stores trimmed, directly presentable short thoughts.`,
-        `- \`${site.contentDirectory}/posts/\` stores full posts; files whose name or path segment starts with \`_\` are drafts and are not published or rendered.`,
+        mappedSections
+            ? "- Thoughts are trimmed, directly presentable notes."
+            : `- \`${site.contentDirectory}/thoughts/\` stores trimmed, directly presentable short thoughts.`,
+        mappedSections
+            ? "- Posts are full articles. Post files whose name or path segment starts with `_` are drafts."
+            : `- \`${site.contentDirectory}/posts/\` stores full posts; files whose name or path segment starts with \`_\` are drafts and are not published or rendered.`,
         "- Content files support `.md` and `.mdx`, and may start with YAML frontmatter.",
         "- Frontmatter currently has no required fields; `title`, `date`, `created_at`, `category` and `tags` are recognized by the site.",
         "",

package/dist/src/skills.d.ts

@@ -36,6 +36,7 @@ export interface Skill {
     relations: SkillRelation[];
 }
 export interface LoadSkillsOptions {
+    includeProjectSkills?: boolean;
     projectRootDirectory?: string;
 }
 export declare function loadSkills(rootDirectory: string, options?: LoadSkillsOptions): Promise<Skill[]>;

package/dist/src/skills.js

@@ -1,4 +1,4 @@
-import { readdir, readFile } from "node:fs/promises";
+import { lstat, readdir, readFile } from "node:fs/promises";
 import { extname, posix, relative, resolve, sep } from "node:path";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { parse as parseYaml } from "yaml";
@@ -90,7 +90,7 @@ async function collectFiles(directory) {
         const path = resolve(directory, entry.name);
         if (entry.isDirectory())
             files.push(...(await collectFiles(path)));
-        else
+        else if (entry.isFile())
             files.push(path);
     }
     return files;
@@ -295,15 +295,21 @@ async function skillDirectories(rootDirectory, options = {}) {
             base: "skills",
             scope: "public",
         },
-        {
-            root: resolve(projectRootDirectory, ".agents/skills"),
-            base: ".agents/skills",
-            scope: "project",
-        },
+        ...(options.includeProjectSkills
+            ? [
+                {
+                    root: resolve(projectRootDirectory, ".agents/skills"),
+                    base: ".agents/skills",
+                    scope: "project",
+                },
+            ]
+            : []),
     ];
     const directories = [];
     for (const candidate of candidates) {
         try {
+            if ((await lstat(candidate.root)).isSymbolicLink())
+                continue;
             const entries = await readdir(candidate.root, { withFileTypes: true });
             directories.push(...entries
                 .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meowpress",
-  "version": "0.3.0-alpha.2",
+  "version": "0.3.0-alpha.3",
   "license": "MIT",
   "type": "module",
   "scripts": {