waymark-docs 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Waymark are documented in this file.
 
+## [0.2.1](https://github.com/ysfaran/waymark/compare/v0.2.0...v0.2.1) (2026-08-13)
+
+
+### Documentation
+
+* **readme:** explain where Waymark fits ([ffe25dc](https://github.com/ysfaran/waymark/commit/ffe25dc15f1651519ad34e9e67f7fee90c69ef62))
+
+## [0.2.0](https://github.com/ysfaran/waymark/compare/v0.1.1...v0.2.0) (2026-08-03)
+
+
+### Features
+
+* **cli:** change require-tags shorthand to -T ([#3](https://github.com/ysfaran/waymark/issues/3)) ([70a95f6](https://github.com/ysfaran/waymark/commit/70a95f6f876e4b48040d778d15bc9189c6020646))
+
 ## [0.1.1](https://github.com/ysfaran/waymark/compare/v0.1.0...v0.1.1) (2026-08-03)
 
 

package/README.md

@@ -1,14 +1,16 @@
 # 🪧 Waymark
 
-Find the right repository docs for your coding agent.
+[![npm version](https://img.shields.io/npm/v/waymark-docs.svg)](https://www.npmjs.com/package/waymark-docs)
 
-Waymark is a small, offline-first CLI built for AI agents. Add structured
-frontmatter to Markdown or MDX files, then let the agent select the kinds and
-tags relevant to its task. Waymark returns deterministic matches without
-ranking results or maintaining an index.
+Waymark is a small, offline-first CLI that helps coding agents find the right
+repository docs for each task. Add structured frontmatter to existing Markdown
+or MDX files, and agents can discover only relevant paths before opening a
+document—without reading a large index or following linked navigation files
+that load unrelated context. It is as easy to set up as file-based navigation,
+but remains deterministic and token-efficient; unlike RAG or MCP-backed
+retrieval, it needs no ranking, maintained index, or retrieval infrastructure.
 
-This makes documentation discovery token-efficient: agents spend less time
-searching unrelated files and more time working with the context they need.
+![Waymark reduces the effort required to find relevant context without retrieval infrastructure.](https://raw.githubusercontent.com/ysfaran/waymark/main/docs/assets/why-waymark.svg)
 
 ## Table of contents
 
@@ -35,23 +37,19 @@ npm install --save-dev waymark-docs
 
 ## Quick start
 
-1. Create a Waymark configuration in the repository root:
+1. **Create a Waymark configuration.**
+
+   Run `init` in the repository root:
 
    ```sh
    npx waymark init
    ```
 
-2. Define the document kinds and tags that agents can search:
-
-   ```yaml
-   # When true, document metadata must be nested under a `waymark` frontmatter key.
-   require-namespace: false
+2. **Define searchable metadata.**
 
-   # Skip generated or vendored documentation during discovery.
-   ignore:
-     - docs/generated/**
-     - vendor/**
+   Add the document kinds and tags that agents can search:
 
+   ```yaml
    kinds:
      adr: Read to understand past architectural decisions and their constraints
      convention: Read before changing code to follow required repository practices
@@ -61,11 +59,10 @@ npm install --save-dev waymark-docs
      typescript: TypeScript-related documentation
    ```
 
-   Ignore patterns are relative to the repository root and support `*`, `?`,
-   and `**` wildcards. Waymark also honors `.gitignore` automatically.
+3. **Register a document.**
 
-3. Register a Markdown or MDX file by adding Waymark metadata. For example,
-   save this as `docs/conventions/typescript.md`:
+   Add Waymark metadata to a Markdown or MDX file. For example, save this as
+   `docs/conventions/typescript.md`:
 
    ```yaml
    ---
@@ -76,7 +73,9 @@ npm install --save-dev waymark-docs
    # TypeScript conventions
    ```
 
-4. Validate the repository:
+4. **Validate the repository.**
+
+   Check the configuration and discovered documents:
 
    ```sh
    npx waymark status
@@ -91,7 +90,9 @@ npm install --save-dev waymark-docs
    Tags: 2
    ```
 
-5. Discover the document:
+5. **Discover the document.**
+
+   Find the registered convention by kind and tag:
 
    ```sh
    npx waymark find --kinds convention --tags typescript --show description
@@ -143,6 +144,19 @@ tags:
   example-tag: Explain the topic represented by this tag
 ```
 
+To skip generated or vendored documentation during discovery, add `ignore`
+patterns:
+
+```yaml
+# Skip generated or vendored documentation during discovery.
+ignore:
+  - docs/generated/**
+  - vendor/**
+```
+
+Ignore patterns are relative to the repository root and support `*`, `?`, and
+`**` wildcards. Waymark also honors `.gitignore` automatically.
+
 `init` never overwrites an existing configuration and does not allow a nested
 configuration beneath another Waymark root.
 
@@ -190,7 +204,7 @@ Usage: waymark find [options]
 Options:
   -k, --kinds <identifiers>         Match any kind (comma-separated, repeatable)
   -t, --tags <identifiers>          Match any tag (comma-separated, repeatable)
-  -r, --require-tags <identifiers>  Require every tag (comma-separated, repeatable)
+  -T, --require-tags <identifiers>  Require every tag (comma-separated, repeatable)
   -f, --filter <expression>         Match a Boolean metadata filter
   -q, --query <text>                Match a literal content query
   -s, --show <fields>               Show kind, tags, and description

package/dist/commands/find.js

@@ -7,7 +7,7 @@ export function createFindCommand() {
         .description("Discover Waymark Documents")
         .option("-k, --kinds <identifiers>", "Match any Document Kind (comma-separated, repeatable)", collectOptionValue, [])
         .option("-t, --tags <identifiers>", "Match any Document Tag (comma-separated, repeatable)", collectOptionValue, [])
-        .option("-r, --require-tags <identifiers>", "Require every Document Tag (comma-separated, repeatable)", collectOptionValue, [])
+        .option("-T, --require-tags <identifiers>", "Require every Document Tag (comma-separated, repeatable)", collectOptionValue, [])
         .option("-f, --filter <expression>", "Match a Boolean Metadata Filter")
         .option("-q, --query <text>", "Match a literal Content Query")
         .option("-s, --show <fields>", "Show kind, tags, and description (comma-separated)")
@@ -25,27 +25,45 @@ export function createFindCommand() {
         }
         const shownFields = parseShownFields(options.show);
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
+        if (loadedConfiguration.kind === "invalid") {
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const { configuration, rootPath } = loadedConfiguration;
+        const metadataCriteria = options.filter === undefined
+            ? {
+                method: "filter-groups",
+                kinds: parseIdentifierOptions({
+                    optionName: "--kinds",
+                    values: options.kinds,
+                    declarations: configuration.kinds,
+                    declarationName: "kind",
+                }),
+                tags: parseIdentifierOptions({
+                    optionName: "--tags",
+                    values: options.tags,
+                    declarations: configuration.tags,
+                    declarationName: "tag",
+                }),
+                requiredTags: parseIdentifierOptions({
+                    optionName: "--require-tags",
+                    values: options.requireTags,
+                    declarations: configuration.tags,
+                    declarationName: "tag",
+                }),
+            }
+            : {
+                method: "filter-expression",
+                expression: options.filter,
+            };
         const documentScan = await scanDocuments({ rootPath, configuration });
-        const diagnostics = [
-            ...loadedConfiguration.diagnostics,
-            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
-        ].sort(compareDiagnostics);
-        if (loadedConfiguration.diagnostics.length > 0 ||
-            documentScan.kind === "invalid") {
-            throwDiagnostics(diagnostics);
+        if (documentScan.kind === "invalid") {
+            throwDiagnostics(documentScan.diagnostics.sort(compareDiagnostics));
         }
         const matchingDocuments = filterDocuments({
             documents: documentScan.documents,
             configuration,
             criteria: {
-                kinds: options.kinds,
-                tags: options.tags,
-                requiredTags: options.requireTags,
-                filter: options.filter,
+                metadata: metadataCriteria,
                 query: options.query,
             },
         });
@@ -171,6 +189,24 @@ function createTreeDirectory() {
 function collectOptionValue(value, previous) {
     return [...previous, value];
 }
+function parseIdentifierOptions({ optionName, values, declarations, declarationName, }) {
+    const identifiers = new Set();
+    for (const value of values) {
+        for (const identifier of value.split(",")) {
+            if (identifier === "") {
+                throw new Error(`${optionName} contains an empty identifier.`);
+            }
+            if (identifiers.has(identifier)) {
+                throw new Error(`${optionName} contains duplicate identifier "${identifier}".`);
+            }
+            if (!declarations.has(identifier)) {
+                throw new Error(`${optionName} contains undeclared ${declarationName} "${identifier}".`);
+            }
+            identifiers.add(identifier);
+        }
+    }
+    return identifiers;
+}
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }

package/dist/commands/ls.js

@@ -11,10 +11,7 @@ export function createLsCommand() {
         .option("-u, --unregistered", "List only Unregistered Documents")
         .action(async (directory, options) => {
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
-            throwDiagnostics(loadedConfiguration.diagnostics);
-        }
-        if (loadedConfiguration.diagnostics.length > 0) {
+        if (loadedConfiguration.kind === "invalid") {
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const rootPath = loadedConfiguration.rootPath;

package/dist/commands/status.js

@@ -9,20 +9,15 @@ export function createStatusCommand() {
         .action(async (options) => {
         const shownFields = parseShownFields(options.show);
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
+        if (loadedConfiguration.kind === "invalid") {
             process.stdout.write(`Root: ${loadedConfiguration.rootPath}\n` + "Status: invalid\n");
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const { configuration, rootPath } = loadedConfiguration;
         const documentScan = await scanDocuments({ rootPath, configuration });
-        const diagnostics = [
-            ...loadedConfiguration.diagnostics,
-            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
-        ].sort(compareDiagnostics);
-        if (loadedConfiguration.diagnostics.length > 0 ||
-            documentScan.kind === "invalid") {
+        if (documentScan.kind === "invalid") {
             process.stdout.write(`Root: ${rootPath}\n` + "Status: invalid\n");
-            throwDiagnostics(diagnostics);
+            throwDiagnostics(documentScan.diagnostics.sort(compareDiagnostics));
         }
         let output = `Root: ${rootPath}\n` +
             "Status: valid\n" +

package/dist/configuration/load.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export declare const defaultConfigFileName = "waymark.yml";
 export declare const allowedConfigFileNames: readonly ["waymark.yml", "waymark.yaml"];
 export type ConfigurationDeclaration = {
@@ -8,22 +9,33 @@ export type ConfigurationDiagnostic = {
     field: string;
     message: string;
 };
-export type Configuration = {
+declare const configurationSchema: z.ZodPipe<z.ZodObject<{
+    "require-namespace": z.ZodDefault<z.ZodBoolean>;
+    kinds: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Record<string, unknown>>>;
+    tags: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Record<string, unknown>>>;
+    ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodTransform<{
     requireNamespace: boolean;
     kinds: Map<string, ConfigurationDeclaration>;
     tags: Map<string, ConfigurationDeclaration>;
     ignorePatterns: string[];
-};
+}, {
+    "require-namespace": boolean;
+    kinds: Map<string, ConfigurationDeclaration>;
+    tags: Map<string, ConfigurationDeclaration>;
+    ignore: string[];
+}>>;
+export type Configuration = z.infer<typeof configurationSchema>;
 export type ConfigurationLoadResult = {
     kind: "loaded";
     rootPath: string;
     configuration: Configuration;
-    diagnostics: ConfigurationDiagnostic[];
 } | {
-    kind: "malformed";
+    kind: "invalid";
     rootPath: string;
     diagnostics: ConfigurationDiagnostic[];
 };
 export declare function loadConfiguration(startingDirectoryPath: string): Promise<ConfigurationLoadResult>;
 export declare function findConfigurationPath(startingDirectoryPath: string): Promise<string | undefined>;
 export declare function findConfigurationPathInDirectory(directoryPath: string): Promise<string | undefined>;
+export {};

package/dist/configuration/load.js

@@ -1,12 +1,80 @@
 import { readFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { parse } from "yaml";
+import { z } from "zod";
+import { compareDiagnostics } from "../diagnostics.js";
 import { pathExists } from "../filesystem.js";
 export const defaultConfigFileName = "waymark.yml";
 export const allowedConfigFileNames = [
     defaultConfigFileName,
     "waymark.yaml",
 ];
+const ignorePatternSchema = z
+    .string({ error: "Ignore glob must be a non-empty string." })
+    .superRefine((pattern, context) => {
+    if (pattern.trim() === "") {
+        context.addIssue({
+            code: "custom",
+            message: "Ignore glob must be a non-empty string.",
+        });
+        return;
+    }
+    if (pattern.startsWith("!")) {
+        context.addIssue({
+            code: "custom",
+            message: "Negation is not supported in ignore globs.",
+        });
+        return;
+    }
+    if (/[![\]{}()]/.test(pattern)) {
+        context.addIssue({
+            code: "custom",
+            message: "Only *, ?, and ** wildcard syntax is supported.",
+        });
+    }
+});
+const configurationDeclarationsSchema = z
+    .record(z.string(), z.unknown(), { error: "Expected a mapping." })
+    .superRefine((declarations, context) => {
+    for (const [identifier, description] of Object.entries(declarations)) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identifier)) {
+            context.addIssue({
+                code: "custom",
+                path: [identifier],
+                message: "Identifier must use lowercase kebab-case.",
+            });
+        }
+        if (typeof description !== "string" || description.trim() === "") {
+            context.addIssue({
+                code: "custom",
+                path: [identifier],
+                message: "Description must be a non-empty string.",
+            });
+        }
+    }
+})
+    .transform((declarations) => new Map(Object.entries(declarations)
+    .filter((entry) => typeof entry[1] === "string")
+    .map(([identifier, description]) => [identifier, { description }])));
+const configurationSchema = z
+    .strictObject({
+    "require-namespace": z
+        .boolean({ error: "Expected a boolean." })
+        .default(false),
+    kinds: configurationDeclarationsSchema,
+    tags: configurationDeclarationsSchema,
+    ignore: z
+        .array(ignorePatternSchema, {
+        error: "Expected a sequence of ignore globs.",
+    })
+        .default([]),
+}, { error: "Expected a mapping." })
+    .transform((configuration) => ({
+    requireNamespace: configuration["require-namespace"],
+    kinds: configuration.kinds,
+    tags: configuration.tags,
+    ignorePatterns: configuration.ignore,
+}));
 export async function loadConfiguration(startingDirectoryPath) {
     const configurationPath = await findConfigurationPath(startingDirectoryPath);
     if (!configurationPath) {
@@ -20,7 +88,7 @@ export async function loadConfiguration(startingDirectoryPath) {
     }
     catch {
         return {
-            kind: "malformed",
+            kind: "invalid",
             rootPath,
             diagnostics: [
                 {
@@ -31,16 +99,21 @@ export async function loadConfiguration(startingDirectoryPath) {
             ],
         };
     }
-    const diagnostics = [];
+    const configurationResult = configurationSchema.safeParse(parsedConfiguration);
+    if (!configurationResult.success) {
+        return {
+            kind: "invalid",
+            rootPath,
+            diagnostics: createConfigurationDiagnostics({
+                error: configurationResult.error,
+                configurationFileName: loadedConfigurationFileName,
+            }),
+        };
+    }
     return {
         kind: "loaded",
         rootPath,
-        configuration: validateConfiguration({
-            value: parsedConfiguration,
-            configurationFileName: loadedConfigurationFileName,
-            diagnostics,
-        }),
-        diagnostics,
+        configuration: configurationResult.data,
     };
 }
 export async function findConfigurationPath(startingDirectoryPath) {
@@ -70,133 +143,25 @@ export async function findConfigurationPathInDirectory(directoryPath) {
     }
     return configurationPaths[0];
 }
-function validateConfiguration({ value, configurationFileName, diagnostics, }) {
-    if (!isRecord(value)) {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "configuration",
-            message: "Expected a mapping.",
-        });
-    }
-    const configuration = isRecord(value) ? value : {};
-    const allowedFields = new Set([
-        "require-namespace",
-        "kinds",
-        "tags",
-        "ignore",
-    ]);
-    for (const field of Object.keys(configuration)) {
-        if (!allowedFields.has(field)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Unknown field.",
-            });
+function createConfigurationDiagnostics({ error, configurationFileName, }) {
+    const diagnostics = [];
+    for (const issue of error.issues) {
+        const field = issue.path.join(".") || "configuration";
+        if (issue.code === "unrecognized_keys") {
+            for (const key of issue.keys) {
+                diagnostics.push({
+                    path: configurationFileName,
+                    field: [...issue.path, key].join("."),
+                    message: "Unknown field.",
+                });
+            }
+            continue;
         }
-    }
-    if (configuration["require-namespace"] !== undefined &&
-        typeof configuration["require-namespace"] !== "boolean") {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "require-namespace",
-            message: "Expected a boolean.",
-        });
-    }
-    return {
-        requireNamespace: configuration["require-namespace"] === true,
-        kinds: validateDeclarations({
-            value: configuration.kinds,
-            field: "kinds",
-            configurationFileName,
-            diagnostics,
-        }),
-        tags: validateDeclarations({
-            value: configuration.tags,
-            field: "tags",
-            configurationFileName,
-            diagnostics,
-        }),
-        ignorePatterns: validateIgnorePatterns({
-            value: configuration.ignore,
-            configurationFileName,
-            diagnostics,
-        }),
-    };
-}
-function validateDeclarations({ value, field, configurationFileName, diagnostics, }) {
-    if (!isRecord(value)) {
         diagnostics.push({
             path: configurationFileName,
             field,
-            message: "Expected a mapping.",
-        });
-        return new Map();
-    }
-    const declarations = new Map();
-    for (const [identifier, description] of Object.entries(value)) {
-        const diagnosticField = `${field}.${identifier}`;
-        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identifier)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field: diagnosticField,
-                message: "Identifier must use lowercase kebab-case.",
-            });
-        }
-        if (typeof description !== "string" || description.trim() === "") {
-            diagnostics.push({
-                path: configurationFileName,
-                field: diagnosticField,
-                message: "Description must be a non-empty string.",
-            });
-        }
-        declarations.set(identifier, {
-            description: typeof description === "string" ? description : "",
-        });
-    }
-    return declarations;
-}
-function validateIgnorePatterns({ value, configurationFileName, diagnostics, }) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value)) {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "ignore",
-            message: "Expected a sequence of ignore globs.",
+            message: issue.message,
         });
-        return [];
     }
-    const ignorePatterns = [];
-    for (const [index, pattern] of value.entries()) {
-        const field = `ignore.${index}`;
-        if (typeof pattern !== "string" || pattern.trim() === "") {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Ignore glob must be a non-empty string.",
-            });
-            continue;
-        }
-        if (pattern.startsWith("!")) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Negation is not supported in ignore globs.",
-            });
-            continue;
-        }
-        if (/[![\]{}()]/.test(pattern)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Only *, ?, and ** wildcard syntax is supported.",
-            });
-            continue;
-        }
-        ignorePatterns.push(pattern);
-    }
-    return ignorePatterns;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return diagnostics.sort(compareDiagnostics);
 }

package/dist/documents/classify.d.ts

@@ -1,8 +1,6 @@
+import { z } from "zod";
 import type { ConfigurationDeclaration } from "../configuration/index.js";
-type ClassifiedDocument = {
-    kind: string;
-    description: string;
-    tags: string[];
+type ClassifiedDocument = z.infer<ReturnType<typeof createDocumentSchema>> & {
     body: string;
 };
 type DocumentDiagnostic = {
@@ -26,4 +24,12 @@ export declare function classifyDocument({ source, requireNamespace, declaredKin
     declaredTags: Map<string, ConfigurationDeclaration>;
     path: string;
 }): DocumentClassification;
+declare function createDocumentSchema({ declaredKinds, declaredTags, }: {
+    declaredKinds: Map<string, ConfigurationDeclaration>;
+    declaredTags: Map<string, ConfigurationDeclaration>;
+}): z.ZodObject<{
+    kind: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<string[], unknown[]>>;
+}, z.core.$strict>;
 export {};

package/dist/documents/classify.js

@@ -1,4 +1,6 @@
 import { parse } from "yaml";
+import { z } from "zod";
+const rawFrontmatterSchema = z.record(z.string(), z.unknown());
 export function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }) {
     const frontmatter = readFrontmatter(source);
     if (frontmatter.kind === "malformed") {
@@ -13,11 +15,14 @@ export function classifyDocument({ source, requireNamespace, declaredKinds, decl
             ],
         };
     }
-    if (frontmatter.kind === "none" || !isRecord(frontmatter.value)) {
+    if (frontmatter.kind === "none") {
         return { kind: "unregistered" };
     }
+    const frontmatterResult = rawFrontmatterSchema.safeParse(frontmatter.value);
+    if (!frontmatterResult.success)
+        return { kind: "unregistered" };
     return validateRegistration({
-        frontmatter: frontmatter.value,
+        frontmatter: frontmatterResult.data,
         body: frontmatter.body,
         requireNamespace,
         declaredKinds,
@@ -52,152 +57,126 @@ function validateRegistration({ frontmatter, body, requireNamespace, declaredKin
     if (!requireNamespace && !hasNamespace && !hasRecognizedFlatMetadata) {
         return { kind: "unregistered" };
     }
-    const diagnostics = [];
     if (hasNamespace && hasRecognizedFlatMetadata) {
-        diagnostics.push({
-            path,
-            field: "waymark",
-            message: "Flat and namespaced metadata cannot both be declared.",
-        });
-        return { kind: "invalid", diagnostics };
+        return {
+            kind: "invalid",
+            diagnostics: [
+                {
+                    path,
+                    field: "waymark",
+                    message: "Flat and namespaced metadata cannot both be declared.",
+                },
+            ],
+        };
     }
     const namespaced = hasNamespace;
-    const value = namespaced ? frontmatter.waymark : frontmatter;
+    const value = namespaced
+        ? frontmatter.waymark
+        : {
+            kind: frontmatter.kind,
+            description: frontmatter.description,
+            tags: frontmatter.tags,
+        };
     const fieldPrefix = namespaced ? "waymark." : "";
-    if (!isRecord(value)) {
-        diagnostics.push({
-            path,
-            field: namespaced ? "waymark" : "frontmatter",
-            message: "Expected a mapping.",
-        });
-        return { kind: "invalid", diagnostics };
-    }
-    if (namespaced) {
-        const allowedFields = new Set(["kind", "description", "tags"]);
-        for (const field of Object.keys(value)) {
-            if (!allowedFields.has(field)) {
-                diagnostics.push({
-                    path,
-                    field: `${fieldPrefix}${field}`,
-                    message: "Unknown field.",
-                });
-            }
-        }
-    }
-    const context = { path, declaredKinds, declaredTags, diagnostics };
-    const kind = validateDocumentKind({
-        value: value.kind,
-        field: `${fieldPrefix}kind`,
-        context,
-    });
-    const description = validateDocumentDescription({
-        value: value.description,
-        field: `${fieldPrefix}description`,
-        context,
-    });
-    const tags = validateDocumentTags({
-        value: value.tags,
-        field: `${fieldPrefix}tags`,
-        context,
-    });
-    if (diagnostics.length > 0 ||
-        kind === undefined ||
-        description === undefined ||
-        tags === undefined) {
-        return { kind: "invalid", diagnostics };
+    const metadataResult = createDocumentSchema({
+        declaredKinds,
+        declaredTags,
+    }).safeParse(value);
+    if (!metadataResult.success) {
+        return {
+            kind: "invalid",
+            diagnostics: createDocumentDiagnostics({
+                error: metadataResult.error,
+                path,
+                fieldPrefix,
+                rootField: namespaced ? "waymark" : "frontmatter",
+            }),
+        };
     }
     return {
         kind: "registered",
-        document: { kind, description, tags, body },
+        document: { ...metadataResult.data, body },
     };
 }
-function validateDocumentKind({ value, field, context, }) {
-    if (value === undefined) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document kind is required.",
-        });
-        return undefined;
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document kind must be a non-empty string.",
-        });
-        return undefined;
-    }
-    if (!context.declaredKinds.has(value)) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: `Undeclared kind "${value}".`,
-        });
-    }
-    return value;
-}
-function validateDocumentDescription({ value, field, context, }) {
-    if (value === undefined) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document Description is required.",
-        });
-        return undefined;
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document Description must be a non-empty string.",
-        });
-        return undefined;
-    }
-    return value;
+function createDocumentSchema({ declaredKinds, declaredTags, }) {
+    return z.strictObject({
+        kind: z
+            .string({
+            error: (issue) => issue.input === undefined
+                ? "Document kind is required."
+                : "Document kind must be a non-empty string.",
+        })
+            .refine((kind) => kind.trim() !== "", {
+            error: "Document kind must be a non-empty string.",
+        })
+            .superRefine((kind, context) => {
+            if (kind.trim() !== "" && !declaredKinds.has(kind)) {
+                context.addIssue({
+                    code: "custom",
+                    message: `Undeclared kind "${kind}".`,
+                });
+            }
+        }),
+        description: z
+            .string({
+            error: (issue) => issue.input === undefined
+                ? "Document Description is required."
+                : "Document Description must be a non-empty string.",
+        })
+            .refine((description) => description.trim() !== "", {
+            error: "Document Description must be a non-empty string.",
+        }),
+        tags: z
+            .array(z.unknown(), { error: "Expected a YAML sequence of tags." })
+            .default([])
+            .superRefine((tags, context) => {
+            const seenTags = new Set();
+            for (const tag of tags) {
+                if (typeof tag !== "string" || tag.trim() === "") {
+                    context.addIssue({
+                        code: "custom",
+                        message: "Every tag must be a non-empty string.",
+                    });
+                    continue;
+                }
+                if (seenTags.has(tag)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Duplicate tag "${tag}".`,
+                    });
+                    continue;
+                }
+                seenTags.add(tag);
+                if (!declaredTags.has(tag)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Undeclared tag "${tag}".`,
+                    });
+                }
+            }
+        })
+            .transform((tags) => tags.filter((tag) => typeof tag === "string")),
+    }, { error: "Expected a mapping." });
 }
-function validateDocumentTags({ value, field, context, }) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value)) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Expected a YAML sequence of tags.",
-        });
-        return undefined;
-    }
-    const tags = [];
-    const seenTags = new Set();
-    for (const tag of value) {
-        if (typeof tag !== "string" || tag.trim() === "") {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: "Every tag must be a non-empty string.",
-            });
-            continue;
-        }
-        if (seenTags.has(tag)) {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: `Duplicate tag "${tag}".`,
-            });
+function createDocumentDiagnostics({ error, path, fieldPrefix, rootField, }) {
+    const diagnostics = [];
+    for (const issue of error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            for (const key of issue.keys) {
+                diagnostics.push({
+                    path,
+                    field: `${fieldPrefix}${key}`,
+                    message: "Unknown field.",
+                });
+            }
             continue;
         }
-        seenTags.add(tag);
-        tags.push(tag);
-        if (!context.declaredTags.has(tag)) {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: `Undeclared tag "${tag}".`,
-            });
-        }
+        const field = issue.path.find((segment) => typeof segment === "string");
+        diagnostics.push({
+            path,
+            field: field === undefined ? rootField : `${fieldPrefix}${field}`,
+            message: issue.message,
+        });
     }
-    return tags;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return diagnostics;
 }

package/dist/documents/filter.d.ts

@@ -4,11 +4,17 @@ type FilterableDocument = {
     kind: string;
     tags: string[];
 };
+type MetadataCriteria = {
+    method: "filter-groups";
+    kinds: Set<string>;
+    tags: Set<string>;
+    requiredTags: Set<string>;
+} | {
+    method: "filter-expression";
+    expression: string;
+};
 type DocumentCriteria = {
-    kinds: string[];
-    tags: string[];
-    requiredTags: string[];
-    filter?: string;
+    metadata: MetadataCriteria;
     query?: string;
 };
 export declare function filterDocuments({ documents, configuration, criteria, }: {

package/dist/documents/filter.js

@@ -1,36 +1,18 @@
 export function filterDocuments({ documents, configuration, criteria, }) {
-    const kinds = parseIdentifierOptions({
-        optionName: "--kinds",
-        values: criteria.kinds,
-        declarations: configuration.kinds,
-        declarationName: "kind",
-    });
-    const tags = parseIdentifierOptions({
-        optionName: "--tags",
-        values: criteria.tags,
-        declarations: configuration.tags,
-        declarationName: "tag",
-    });
-    const requiredTags = parseIdentifierOptions({
-        optionName: "--require-tags",
-        values: criteria.requiredTags,
-        declarations: configuration.tags,
-        declarationName: "tag",
-    });
-    const matchesMetadataFilter = criteria.filter === undefined
-        ? undefined
-        : parseMetadataFilter({
-            expression: criteria.filter,
+    const metadata = criteria.metadata;
+    const matchesMetadata = metadata.method === "filter-expression"
+        ? parseMetadataFilter({
+            expression: metadata.expression,
             declaredKinds: new Set(configuration.kinds.keys()),
             declaredTags: new Set(configuration.tags.keys()),
-        });
+        })
+        : (document) => (metadata.kinds.size === 0 || metadata.kinds.has(document.kind)) &&
+            (metadata.tags.size === 0 ||
+                document.tags.some((tag) => metadata.tags.has(tag))) &&
+            [...metadata.requiredTags].every((tag) => document.tags.includes(tag));
     const normalizedQuery = criteria.query?.toLowerCase();
     return documents
-        .filter((document) => (kinds.size === 0 || kinds.has(document.kind)) &&
-        (tags.size === 0 || document.tags.some((tag) => tags.has(tag))) &&
-        [...requiredTags].every((tag) => document.tags.includes(tag)) &&
-        (matchesMetadataFilter === undefined ||
-            matchesMetadataFilter(document)) &&
+        .filter((document) => matchesMetadata(document) &&
         (normalizedQuery === undefined ||
             document.body.toLowerCase().includes(normalizedQuery)))
         .sort((left, right) => compareText(left.path, right.path));
@@ -189,24 +171,6 @@ function describeToken(token) {
         return '"("';
     return `"${token.type.toUpperCase()}"`;
 }
-function parseIdentifierOptions({ optionName, values, declarations, declarationName, }) {
-    const identifiers = new Set();
-    for (const value of values) {
-        for (const identifier of value.split(",")) {
-            if (identifier === "") {
-                throw new Error(`${optionName} contains an empty identifier.`);
-            }
-            if (identifiers.has(identifier)) {
-                throw new Error(`${optionName} contains duplicate identifier "${identifier}".`);
-            }
-            if (!declarations.has(identifier)) {
-                throw new Error(`${optionName} contains undeclared ${declarationName} "${identifier}".`);
-            }
-            identifiers.add(identifier);
-        }
-    }
-    return identifiers;
-}
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waymark-docs",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Agent-focused CLI that surfaces repository documentation to improve coding-agent performance.",
   "keywords": [
     "ai-agents",
@@ -45,7 +45,8 @@
   "dependencies": {
     "commander": "14.0.3",
     "globby": "16.2.2",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "24.10.10",