waymark-docs 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Waymark are documented in this file.
 
+## [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)
+
+
+### Features
+
+* **cli:** add Waymark documentation discovery CLI ([ea0e515](https://github.com/ysfaran/waymark/commit/ea0e515479b323448b2a76c84c343ea314786093))
+
 ## 0.1.0 (2026-07-31)
 
 - Initial public release.

package/README.md

@@ -1,4 +1,4 @@
-# Waymark 🪧
+# 🪧 Waymark
 
 Find the right repository docs for your coding agent.
 
@@ -35,18 +35,19 @@ npm install --save-dev waymark-docs
 
 ## Quick start
 
-1. Create `waymark.yaml` 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:
+2. **Define searchable metadata.**
 
-   ```yaml
-   # When true, document metadata must be nested under a `waymark` frontmatter key.
-   require-namespace: false
+   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
@@ -56,8 +57,10 @@ npm install --save-dev waymark-docs
      typescript: TypeScript-related documentation
    ```
 
-3. Register a Markdown or MDX file by adding Waymark metadata. For example,
-   save this as `docs/conventions/typescript.md`:
+3. **Register a document.**
+
+   Add Waymark metadata to a Markdown or MDX file. For example, save this as
+   `docs/conventions/typescript.md`:
 
    ```yaml
    ---
@@ -68,7 +71,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
@@ -83,7 +88,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
@@ -93,8 +100,10 @@ npm install --save-dev waymark-docs
    docs/conventions/typescript.md — TypeScript conventions for this repository
    ```
 
-Waymark looks for `waymark.yaml` in the current directory and its ancestors, so
-commands can also be run from a nested repository directory.
+Waymark uses `waymark.yml` by default and also recognizes `waymark.yaml`. It
+looks for the configuration in the current directory and its ancestors, so
+commands can also run from a nested repository directory. Use only one filename
+per directory.
 
 ## Commands
 
@@ -108,7 +117,7 @@ commands can also be run from a nested repository directory.
 
 ### `waymark init`
 
-Create a starter `waymark.yaml` in the current directory.
+Create a starter configuration in the current directory.
 
 ```text
 Usage: waymark init [options]
@@ -133,15 +142,28 @@ 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.
 
 ### `waymark status`
 
-Validate `waymark.yaml` and all discovered Waymark Documents, then print the
-repository root and counts for registered documents, unregistered documents,
-kinds, and tags. Invalid repositories produce diagnostics and a non-zero exit
-code, which makes this command suitable for CI.
+Validate the Waymark configuration and all discovered Waymark Documents, then
+print the repository root and counts for registered documents, unregistered
+documents, kinds, and tags. Invalid repositories produce diagnostics and a
+non-zero exit code, which makes this command suitable for CI.
 
 ```text
 Usage: waymark status [options]
@@ -180,7 +202,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
@@ -280,7 +302,7 @@ Find Markdown and MDX files that are missing Waymark metadata:
 npx waymark ls -R --unregistered docs
 ```
 
-`ls` respects `.gitignore`, Waymark exclusions, and Git directory boundaries.
+`ls` respects `.gitignore`, Waymark ignore patterns, and Git directory boundaries.
 The selected directory must be inside the repository root.
 
 ### `waymark help`

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)")

package/dist/configuration/index.d.ts

@@ -1,3 +1,3 @@
 export { initializeConfiguration } from "./initialize.js";
-export { configurationFileName, loadConfiguration } from "./load.js";
+export { allowedConfigFileNames, defaultConfigFileName, loadConfiguration, } from "./load.js";
 export type { Configuration, ConfigurationDeclaration, ConfigurationDiagnostic, ConfigurationLoadResult, } from "./load.js";

package/dist/configuration/index.js

@@ -1,2 +1,2 @@
 export { initializeConfiguration } from "./initialize.js";
-export { configurationFileName, loadConfiguration } from "./load.js";
+export { allowedConfigFileNames, defaultConfigFileName, loadConfiguration, } from "./load.js";

package/dist/configuration/initialize.js

@@ -1,7 +1,7 @@
 import { writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { isErrorWithCode, pathExists } from "../filesystem.js";
-import { configurationFileName, findConfigurationPath } from "./load.js";
+import { isErrorWithCode } from "../filesystem.js";
+import { defaultConfigFileName, findConfigurationPath, findConfigurationPathInDirectory, } from "./load.js";
 const starterConfiguration = "# When true, document metadata must be nested under a `waymark` frontmatter key.\n" +
     "require-namespace: false\n" +
     "kinds:\n" +
@@ -9,9 +9,10 @@ const starterConfiguration = "# When true, document metadata must be nested unde
     "tags:\n" +
     "  example-tag: Explain the topic represented by this tag\n";
 export async function initializeConfiguration(directoryPath) {
-    const configurationPath = join(directoryPath, configurationFileName);
-    if (await pathExists(configurationPath)) {
-        throw new Error(`A Waymark configuration already exists at ${configurationPath}.`);
+    const configurationPath = join(directoryPath, defaultConfigFileName);
+    const existingConfigurationPath = await findConfigurationPathInDirectory(directoryPath);
+    if (existingConfigurationPath) {
+        throw new Error(`A Waymark configuration already exists at ${existingConfigurationPath}.`);
     }
     const ancestorConfigurationPath = await findConfigurationPath(dirname(directoryPath));
     if (ancestorConfigurationPath) {

package/dist/configuration/load.d.ts

@@ -1,4 +1,5 @@
-export declare const configurationFileName: string;
+export declare const defaultConfigFileName = "waymark.yml";
+export declare const allowedConfigFileNames: readonly ["waymark.yml", "waymark.yaml"];
 export type ConfigurationDeclaration = {
     description: string;
 };
@@ -11,7 +12,7 @@ export type Configuration = {
     requireNamespace: boolean;
     kinds: Map<string, ConfigurationDeclaration>;
     tags: Map<string, ConfigurationDeclaration>;
-    exclusions: string[];
+    ignorePatterns: string[];
 };
 export type ConfigurationLoadResult = {
     kind: "loaded";
@@ -25,3 +26,4 @@ export type ConfigurationLoadResult = {
 };
 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>;

package/dist/configuration/load.js

@@ -1,14 +1,19 @@
 import { readFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { parse } from "yaml";
 import { pathExists } from "../filesystem.js";
-export const configurationFileName = "waymark.yaml";
+export const defaultConfigFileName = "waymark.yml";
+export const allowedConfigFileNames = [
+    defaultConfigFileName,
+    "waymark.yaml",
+];
 export async function loadConfiguration(startingDirectoryPath) {
     const configurationPath = await findConfigurationPath(startingDirectoryPath);
     if (!configurationPath) {
-        throw new Error(`Could not find ${configurationFileName} from ${resolve(startingDirectoryPath)}.`);
+        throw new Error(`Could not find ${allowedConfigFileNames.join(" or ")} from ${resolve(startingDirectoryPath)}.`);
     }
     const rootPath = dirname(configurationPath);
+    const loadedConfigurationFileName = basename(configurationPath);
     let parsedConfiguration;
     try {
         parsedConfiguration = parse(await readFile(configurationPath, "utf8"));
@@ -19,7 +24,7 @@ export async function loadConfiguration(startingDirectoryPath) {
             rootPath,
             diagnostics: [
                 {
-                    path: configurationFileName,
+                    path: loadedConfigurationFileName,
                     field: "configuration",
                     message: "Malformed YAML configuration.",
                 },
@@ -30,7 +35,11 @@ export async function loadConfiguration(startingDirectoryPath) {
     return {
         kind: "loaded",
         rootPath,
-        configuration: validateConfiguration(parsedConfiguration, diagnostics),
+        configuration: validateConfiguration({
+            value: parsedConfiguration,
+            configurationFileName: loadedConfigurationFileName,
+            diagnostics,
+        }),
         diagnostics,
     };
 }
@@ -38,17 +47,30 @@ export async function findConfigurationPath(startingDirectoryPath) {
     let directoryPath = resolve(startingDirectoryPath);
     let foundConfigurationPath;
     while (true) {
-        const configurationPath = join(directoryPath, configurationFileName);
-        if (await pathExists(configurationPath)) {
+        const configurationPath = await findConfigurationPathInDirectory(directoryPath);
+        if (configurationPath)
             foundConfigurationPath = configurationPath;
-        }
         const parentPath = dirname(directoryPath);
         if (parentPath === directoryPath)
             return foundConfigurationPath;
         directoryPath = parentPath;
     }
 }
-function validateConfiguration(value, diagnostics) {
+export async function findConfigurationPathInDirectory(directoryPath) {
+    const configurationPaths = [];
+    for (const fileName of allowedConfigFileNames) {
+        const configurationPath = join(directoryPath, fileName);
+        if (await pathExists(configurationPath)) {
+            configurationPaths.push(configurationPath);
+        }
+    }
+    if (configurationPaths.length > 1) {
+        throw new Error(`Multiple Waymark configurations exist in ${resolve(directoryPath)}: ` +
+            `${allowedConfigFileNames.join(", ")}.`);
+    }
+    return configurationPaths[0];
+}
+function validateConfiguration({ value, configurationFileName, diagnostics, }) {
     if (!isRecord(value)) {
         diagnostics.push({
             path: configurationFileName,
@@ -61,7 +83,7 @@ function validateConfiguration(value, diagnostics) {
         "require-namespace",
         "kinds",
         "tags",
-        "exclude",
+        "ignore",
     ]);
     for (const field of Object.keys(configuration)) {
         if (!allowedFields.has(field)) {
@@ -85,17 +107,23 @@ function validateConfiguration(value, diagnostics) {
         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,
         }),
-        exclusions: validateExclusions(configuration.exclude, diagnostics),
     };
 }
-function validateDeclarations({ value, field, diagnostics, }) {
+function validateDeclarations({ value, field, configurationFileName, diagnostics, }) {
     if (!isRecord(value)) {
         diagnostics.push({
             path: configurationFileName,
@@ -127,25 +155,25 @@ function validateDeclarations({ value, field, diagnostics, }) {
     }
     return declarations;
 }
-function validateExclusions(value, diagnostics) {
+function validateIgnorePatterns({ value, configurationFileName, diagnostics, }) {
     if (value === undefined)
         return [];
     if (!Array.isArray(value)) {
         diagnostics.push({
             path: configurationFileName,
-            field: "exclude",
-            message: "Expected a sequence of exclusion globs.",
+            field: "ignore",
+            message: "Expected a sequence of ignore globs.",
         });
         return [];
     }
-    const exclusions = [];
+    const ignorePatterns = [];
     for (const [index, pattern] of value.entries()) {
-        const field = `exclude.${index}`;
+        const field = `ignore.${index}`;
         if (typeof pattern !== "string" || pattern.trim() === "") {
             diagnostics.push({
                 path: configurationFileName,
                 field,
-                message: "Exclusion glob must be a non-empty string.",
+                message: "Ignore glob must be a non-empty string.",
             });
             continue;
         }
@@ -153,7 +181,7 @@ function validateExclusions(value, diagnostics) {
             diagnostics.push({
                 path: configurationFileName,
                 field,
-                message: "Negation is not supported in exclusion globs.",
+                message: "Negation is not supported in ignore globs.",
             });
             continue;
         }
@@ -165,9 +193,9 @@ function validateExclusions(value, diagnostics) {
             });
             continue;
         }
-        exclusions.push(pattern);
+        ignorePatterns.push(pattern);
     }
-    return exclusions;
+    return ignorePatterns;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/documents/scan.js

@@ -1,7 +1,7 @@
 import { lstat, readFile, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
 import { convertPathToPattern, globby } from "globby";
-import { configurationFileName, } from "../configuration/index.js";
+import { allowedConfigFileNames, } from "../configuration/index.js";
 import { isErrorWithCode } from "../filesystem.js";
 import { classifyDocument } from "./classify.js";
 export async function scanDocuments({ rootPath, configuration, scope, }) {
@@ -9,7 +9,7 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
     const discoveredPaths = await globby(createCandidatePatterns(resolvedScope), {
         cwd: scanRootPath,
         gitignore: true,
-        ignore: ["**/.git", "**/.git/**", ...configuration.exclusions],
+        ignore: ["**/.git", "**/.git/**", ...configuration.ignorePatterns],
         dot: true,
         followSymbolicLinks: false,
         braceExpansion: false,
@@ -21,9 +21,9 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
     const diagnostics = [];
     const unregisteredDocuments = [];
     for (const path of discoveredPaths.sort(compareText)) {
-        if (path === configurationFileName)
+        if (allowedConfigFileNames.some((fileName) => fileName === path))
             continue;
-        if (path.endsWith(`/${configurationFileName}`)) {
+        if (allowedConfigFileNames.some((fileName) => path.endsWith(`/${fileName}`))) {
             diagnostics.push({
                 path,
                 field: "configuration",
@@ -102,7 +102,11 @@ async function resolveDocumentScanScope({ rootPath, scope, }) {
 }
 function createCandidatePatterns(scope) {
     if (!scope) {
-        return ["**/*.md", "**/*.mdx", `**/${configurationFileName}`];
+        return [
+            "**/*.md",
+            "**/*.mdx",
+            ...allowedConfigFileNames.map((fileName) => `**/${fileName}`),
+        ];
     }
     const directoryPattern = convertPathToPattern(scope.relativeDirectoryPath);
     const directoryPrefix = directoryPattern === "" ? "" : `${directoryPattern}/`;
@@ -112,7 +116,7 @@ function createCandidatePatterns(scope) {
     return [
         `${candidatePrefix}*.md`,
         `${candidatePrefix}*.mdx`,
-        `${candidatePrefix}${configurationFileName}`,
+        ...allowedConfigFileNames.map((fileName) => `${candidatePrefix}${fileName}`),
     ];
 }
 function createUsageCounts(declarations) {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "waymark-docs",
-  "version": "0.1.0",
-  "description": "Find repository documentation relevant to coding agents",
+  "version": "0.2.0",
+  "description": "Agent-focused CLI that surfaces repository documentation to improve coding-agent performance.",
   "keywords": [
     "ai-agents",
     "cli",
+    "context-engineering",
     "documentation",
-    "markdown",
-    "repository"
+    "markdown"
   ],
   "homepage": "https://github.com/ysfaran/waymark#readme",
   "bugs": {
@@ -37,7 +37,10 @@
     "dev": "tsx src/cli.ts",
     "prepack": "cp ../README.md ../CHANGELOG.md ../LICENSE . && pnpm build",
     "postpack": "rm -f README.md CHANGELOG.md LICENSE",
-    "typecheck": "tsc --project tsconfig.json --noEmit"
+    "test": "pnpm test:unit && pnpm test:integration",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "typecheck": "tsc --project tsconfig.json --noEmit && tsc --project tsconfig.test.json --noEmit"
   },
   "dependencies": {
     "commander": "14.0.3",
@@ -47,7 +50,8 @@
   "devDependencies": {
     "@types/node": "24.10.10",
     "tsx": "4.20.6",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "4.0.18"
   },
   "engines": {
     "node": ">=24"