waypoint-codex 0.13.2 → 0.14.0

package/README.md

@@ -72,6 +72,10 @@ The philosophy is simple:
 - investigation before status narration
 - structured workflows that stay in their own tools
 
+By default, Waypoint routes docs from `.waypoint/docs/` and plans from `.waypoint/plans/`.
+If your repo keeps routable docs elsewhere, you can add more explicit roots in `.waypoint/config.toml` with `docs_dirs` and `plans_dirs`.
+Waypoint scans each configured root recursively and only includes Markdown files with valid Waypoint frontmatter.
+
 ## Best fit
 
 Waypoint is most useful when you want:
@@ -117,6 +121,20 @@ repo/
 
 From there, start your Codex session in the repo and follow the generated bootstrap in `AGENTS.md`.
 
+If you want to add more routable roots, extend `.waypoint/config.toml` like this:
+
+```toml
+docs_dirs = [
+  ".waypoint/docs",
+  "services/app/docs",
+]
+
+plans_dirs = [
+  ".waypoint/plans",
+  "services/app/plans",
+]
+```
+
 ## Built-in skills
 
 Waypoint ships a strong default skill pack for real coding work:

package/dist/src/core.js

@@ -1,9 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import * as TOML from "@iarna/toml";
 import { renderDocsIndex } from "./docs-index.js";
 import { renderTracksIndex } from "./track-index.js";
-import { readTemplate, renderWaypointConfig, MANAGED_BLOCK_END, MANAGED_BLOCK_START, templatePath } from "./templates.js";
+import { defaultWaypointConfig, readTemplate, renderWaypointConfig, MANAGED_BLOCK_END, MANAGED_BLOCK_START, templatePath, } from "./templates.js";
 const DEFAULT_CONFIG_PATH = ".waypoint/config.toml";
 const DEFAULT_DOCS_DIR = ".waypoint/docs";
 const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
@@ -52,6 +52,7 @@ const LEGACY_WAYPOINT_GITIGNORE_RULES = new Set([
     ".waypoint/context/",
     ".waypoint/scripts/",
     ".waypoint/track/",
+    ".waypoint/plans/",
     ".waypoint/*",
     "!.waypoint/docs/",
     "!.waypoint/docs/**",
@@ -83,18 +84,75 @@ const TIMESTAMPED_WORKSPACE_SECTIONS = new Set([
     "## Done Recently",
 ]);
 const TIMESTAMPED_ENTRY_PATTERN = /^(?:[-*]|\d+\.)\s+\[\d{4}-\d{2}-\d{2} \d{2}:\d{2} [A-Z]{2,5}\]/;
+function configuredRootDirs(projectRoot, roots, legacyRoot, fallbackRoot) {
+    const configuredRoots = roots && roots.length > 0
+        ? roots
+        : legacyRoot
+            ? [legacyRoot]
+            : [fallbackRoot];
+    const normalizedRoots = [];
+    const seen = new Set();
+    for (const root of configuredRoots) {
+        const trimmedRoot = root.trim();
+        if (trimmedRoot.length === 0) {
+            continue;
+        }
+        const resolvedRoot = path.resolve(projectRoot, trimmedRoot);
+        let dedupeKey = path.normalize(resolvedRoot);
+        if (existsSync(resolvedRoot)) {
+            try {
+                dedupeKey = realpathSync(resolvedRoot);
+            }
+            catch {
+                dedupeKey = path.normalize(resolvedRoot);
+            }
+        }
+        if (seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        normalizedRoots.push(resolvedRoot);
+    }
+    return normalizedRoots.length > 0 ? normalizedRoots : [path.resolve(projectRoot, fallbackRoot)];
+}
+function docsRootDirs(projectRoot, config) {
+    return configuredRootDirs(projectRoot, config?.docs_dirs, config?.docs_dir, DEFAULT_DOCS_DIR);
+}
+function plansRootDirs(projectRoot, config) {
+    return configuredRootDirs(projectRoot, config?.plans_dirs, config?.plans_dir, DEFAULT_PLANS_DIR);
+}
+function docsSectionHeading(projectRoot, dir) {
+    const relativePath = path.relative(projectRoot, dir).split(path.sep).join("/");
+    const normalizedPath = relativePath.length === 0 ? "." : relativePath;
+    return normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+}
 function docsIndexSections(projectRoot, config) {
     return [
-        {
-            heading: ".waypoint/docs/",
-            dir: path.join(projectRoot, config?.docs_dir ?? DEFAULT_DOCS_DIR),
-        },
-        {
-            heading: ".waypoint/plans/",
-            dir: path.join(projectRoot, config?.plans_dir ?? DEFAULT_PLANS_DIR),
-        },
+        ...docsRootDirs(projectRoot, config).map((dir) => ({
+            heading: docsSectionHeading(projectRoot, dir),
+            dir,
+        })),
+        ...plansRootDirs(projectRoot, config).map((dir) => ({
+            heading: docsSectionHeading(projectRoot, dir),
+            dir,
+        })),
     ];
 }
+function buildWaypointConfig(projectRoot, existingConfig, options) {
+    const defaults = defaultWaypointConfig({ profile: options.profile });
+    return {
+        version: existingConfig?.version ?? defaults.version,
+        profile: options.profile,
+        workspace_file: existingConfig?.workspace_file ?? defaults.workspace_file,
+        docs_dirs: configuredRootDirs(projectRoot, existingConfig?.docs_dirs, existingConfig?.docs_dir, DEFAULT_DOCS_DIR).map((dir) => path.relative(projectRoot, dir).split(path.sep).join("/")),
+        plans_dirs: configuredRootDirs(projectRoot, existingConfig?.plans_dirs, existingConfig?.plans_dir, DEFAULT_PLANS_DIR).map((dir) => path.relative(projectRoot, dir).split(path.sep).join("/")),
+        docs_index_file: existingConfig?.docs_index_file ?? defaults.docs_index_file,
+        features: {
+            repo_skills: existingConfig?.features?.repo_skills ?? defaults.features?.repo_skills,
+            docs_index: existingConfig?.features?.docs_index ?? defaults.features?.docs_index,
+        },
+    };
+}
 function ensureDir(dirPath) {
     mkdirSync(dirPath, { recursive: true });
 }
@@ -287,6 +345,7 @@ function scaffoldOptionalCodex(projectRoot) {
 export function initRepository(projectRoot, options) {
     ensureDir(projectRoot);
     migrateLegacyRootFiles(projectRoot);
+    const config = buildWaypointConfig(projectRoot, loadWaypointConfig(projectRoot), options);
     // Any Waypoint-owned path removed from the scaffold should be added here
     // so `waypoint init` / `waypoint upgrade` can actively prune stale copies.
     for (const deprecatedPath of [
@@ -324,9 +383,7 @@ export function initRepository(projectRoot, options) {
     writeText(path.join(projectRoot, ".waypoint/agent-operating-manual.md"), readTemplate(".waypoint/agent-operating-manual.md"));
     writeIfMissing(path.join(projectRoot, DEFAULT_MEMORY), readTemplate(".waypoint/MEMORY.md"));
     scaffoldWaypointOptionalTemplates(projectRoot);
-    writeText(path.join(projectRoot, DEFAULT_CONFIG_PATH), renderWaypointConfig({
-        profile: options.profile,
-    }));
+    writeText(path.join(projectRoot, DEFAULT_CONFIG_PATH), renderWaypointConfig(config));
     writeIfMissing(path.join(projectRoot, DEFAULT_WORKSPACE), readTemplate("WORKSPACE.md"));
     ensureDir(path.join(projectRoot, DEFAULT_DOCS_DIR));
     ensureDir(path.join(projectRoot, DEFAULT_PLANS_DIR));
@@ -338,9 +395,10 @@ export function initRepository(projectRoot, options) {
     scaffoldSkills(projectRoot);
     scaffoldOptionalCodex(projectRoot);
     appendGitignoreSnippet(projectRoot);
-    const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot));
+    const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
+    const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot, config));
     const tracksIndex = renderTracksIndex(projectRoot, path.join(projectRoot, DEFAULT_TRACK_DIR));
-    writeText(path.join(projectRoot, DEFAULT_DOCS_INDEX), `${docsIndex.content}\n`);
+    writeText(docsIndexPath, `${docsIndex.content}\n`);
     writeText(path.join(projectRoot, DEFAULT_TRACKS_INDEX), `${tracksIndex.content}\n`);
     return [
         "Initialized Waypoint scaffold",
@@ -475,27 +533,33 @@ export function doctorRepository(projectRoot) {
         }
     }
     const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
-    const docsDir = path.join(projectRoot, config.docs_dir ?? DEFAULT_DOCS_DIR);
-    const plansDir = path.join(projectRoot, config.plans_dir ?? DEFAULT_PLANS_DIR);
+    const configuredDocsDirs = docsRootDirs(projectRoot, config);
+    const configuredPlansDirs = plansRootDirs(projectRoot, config);
     const docsIndex = renderDocsIndex(projectRoot, docsIndexSections(projectRoot, config));
     const trackDir = path.join(projectRoot, DEFAULT_TRACK_DIR);
     const tracksIndexPath = path.join(projectRoot, DEFAULT_TRACKS_INDEX);
     const tracksIndex = renderTracksIndex(projectRoot, trackDir);
-    if (!existsSync(docsDir)) {
+    for (const docsDir of configuredDocsDirs) {
+        if (existsSync(docsDir)) {
+            continue;
+        }
         findings.push({
             severity: "error",
             category: "docs",
-            message: ".waypoint/docs/ directory is missing.",
-            remediation: "Run `waypoint init` to scaffold docs.",
+            message: `${docsSectionHeading(projectRoot, docsDir)} directory is missing.`,
+            remediation: "Create the configured docs directory or update `.waypoint/config.toml`.",
             paths: [docsDir],
         });
     }
-    if (!existsSync(plansDir)) {
+    for (const plansDir of configuredPlansDirs) {
+        if (existsSync(plansDir)) {
+            continue;
+        }
         findings.push({
             severity: "error",
             category: "docs",
-            message: ".waypoint/plans/ directory is missing.",
-            remediation: "Run `waypoint init` to scaffold plans.",
+            message: `${docsSectionHeading(projectRoot, plansDir)} directory is missing.`,
+            remediation: "Create the configured plans directory or update `.waypoint/config.toml`.",
             paths: [plansDir],
         });
     }

package/dist/src/docs-index.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import path from "node:path";
 const SKIP_DIRS = new Set([
     ".git",
@@ -50,18 +50,25 @@ function parseFrontmatter(filePath) {
     }
     return { summary, lastUpdated, readWhen };
 }
-function walkDocs(projectRoot, currentDir, output, invalid) {
-    for (const entry of readdirSync(currentDir)) {
-        const fullPath = path.join(currentDir, entry);
-        const stat = statSync(fullPath);
-        if (stat.isDirectory()) {
-            if (SKIP_DIRS.has(entry)) {
+function walkDocs(projectRoot, currentDir, output, invalid, visitedDirs) {
+    const resolvedCurrentDir = realpathSync(currentDir);
+    if (visitedDirs.has(resolvedCurrentDir)) {
+        return;
+    }
+    visitedDirs.add(resolvedCurrentDir);
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name)) {
                 continue;
             }
-            walkDocs(projectRoot, fullPath, output, invalid);
+            walkDocs(projectRoot, fullPath, output, invalid, visitedDirs);
             continue;
         }
-        if (!entry.endsWith(".md") || SKIP_NAMES.has(entry)) {
+        if (!isMarkdownDoc(entry)) {
             continue;
         }
         const { summary, lastUpdated, readWhen } = parseFrontmatter(fullPath);
@@ -77,10 +84,13 @@ function collectDocEntries(projectRoot, docsDir) {
     const entries = [];
     const invalidDocs = [];
     if (existsSync(docsDir)) {
-        walkDocs(projectRoot, docsDir, entries, invalidDocs);
+        walkDocs(projectRoot, docsDir, entries, invalidDocs, new Set());
     }
     return { entries, invalidDocs };
 }
+function isMarkdownDoc(entry) {
+    return entry.isFile() && entry.name.endsWith(".md") && !SKIP_NAMES.has(entry.name);
+}
 export function renderDocsIndex(projectRoot, sections) {
     const lines = [
         "# Docs Index",

package/dist/src/templates.js

@@ -1,3 +1,4 @@
+import * as TOML from "@iarna/toml";
 import { readFileSync } from "node:fs";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -25,7 +26,32 @@ export function templatePath(relativePath) {
 export function readTemplate(relativePath) {
     return readFileSync(templatePath(relativePath), "utf8");
 }
-export function renderWaypointConfig(options) {
-    return readTemplate(".waypoint/config.toml")
-        .replace("__PROFILE__", options.profile);
+export function defaultWaypointConfig(options) {
+    return {
+        version: 1,
+        profile: options.profile,
+        workspace_file: ".waypoint/WORKSPACE.md",
+        docs_dirs: [".waypoint/docs"],
+        plans_dirs: [".waypoint/plans"],
+        docs_index_file: ".waypoint/DOCS_INDEX.md",
+        features: {
+            repo_skills: true,
+            docs_index: true,
+        },
+    };
+}
+export function renderWaypointConfig(config) {
+    const renderedConfig = {
+        version: config.version,
+        profile: config.profile,
+        workspace_file: config.workspace_file,
+        docs_dirs: config.docs_dirs,
+        plans_dirs: config.plans_dirs,
+        docs_index_file: config.docs_index_file,
+        features: config.features ? {
+            repo_skills: config.features.repo_skills,
+            docs_index: config.features.docs_index,
+        } : undefined,
+    };
+    return TOML.stringify(renderedConfig);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.gitignore.snippet

@@ -30,6 +30,7 @@
 .waypoint/scripts/
 .waypoint/state/
 .waypoint/track/
+.waypoint/plans/
 .waypoint/docs/README.md
 .waypoint/docs/code-guide.md
 # End Waypoint state

package/templates/.waypoint/config.toml

@@ -1,8 +1,8 @@
 version = 1
 profile = "__PROFILE__"
 workspace_file = ".waypoint/WORKSPACE.md"
-docs_dir = ".waypoint/docs"
-plans_dir = ".waypoint/plans"
+docs_dirs = [".waypoint/docs"]
+plans_dirs = [".waypoint/plans"]
 docs_index_file = ".waypoint/DOCS_INDEX.md"
 
 [features]