waypoint-codex 0.1.2 → 0.1.4

package/README.md

@@ -5,9 +5,9 @@ Waypoint is a docs-first repository operating system for Codex.
 It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
 
 - `AGENTS.md` for startup instructions
-- `WORKSPACE.md` for live state
+- `.waypoint/WORKSPACE.md` for live state
 - `.waypoint/docs/` for durable project memory
-- `DOCS_INDEX.md` for docs routing
+- `.waypoint/DOCS_INDEX.md` for docs routing
 - repo-local skills for planning and audits
 
 ## Install
@@ -36,10 +36,10 @@ That scaffolds:
 ```text
 repo/
 ├── AGENTS.md
-├── WORKSPACE.md
-├── DOCS_INDEX.md
 ├── .agents/skills/
 └── .waypoint/
+    ├── WORKSPACE.md
+    ├── DOCS_INDEX.md
     ├── docs/
     ├── context/
     └── ...
@@ -49,7 +49,7 @@ repo/
 
 - `waypoint init` — scaffold or refresh the repo
 - `waypoint doctor` — check for drift and missing pieces
-- `waypoint sync` — rebuild `DOCS_INDEX.md` and sync optional automations/rules
+- `waypoint sync` — rebuild `.waypoint/DOCS_INDEX.md` and sync optional automations/rules
 - `waypoint import-legacy` — import from an older repo layout
 
 ## Shipped skills

package/dist/src/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import process from "node:process";
 import { doctorRepository, importLegacyRepo, initRepository, syncRepository } from "./core.js";
-const VERSION = "0.1.0";
+const VERSION = JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")).version;
 function resolveRepo(input) {
     return path.resolve(input ?? ".");
 }

package/dist/src/core.js

@@ -7,8 +7,8 @@ import { renderDocsIndex } from "./docs-index.js";
 import { 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 = "DOCS_INDEX.md";
-const DEFAULT_WORKSPACE = "WORKSPACE.md";
+const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
+const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
 const SYNC_RECORDS_FILE = ".waypoint/state/sync-records.json";
 function ensureDir(dirPath) {
@@ -29,6 +29,15 @@ function removePathIfExists(targetPath) {
         rmSync(targetPath, { recursive: true, force: true });
     }
 }
+function migrateLegacyRootFiles(projectRoot) {
+    const legacyWorkspace = path.join(projectRoot, "WORKSPACE.md");
+    const newWorkspace = path.join(projectRoot, DEFAULT_WORKSPACE);
+    if (existsSync(legacyWorkspace) && !existsSync(newWorkspace)) {
+        writeText(newWorkspace, readFileSync(legacyWorkspace, "utf8"));
+    }
+    removePathIfExists(legacyWorkspace);
+    removePathIfExists(path.join(projectRoot, "DOCS_INDEX.md"));
+}
 function appendGitignoreSnippet(projectRoot) {
     const gitignorePath = path.join(projectRoot, ".gitignore");
     const snippet = readTemplate(".gitignore.snippet").trim();
@@ -90,9 +99,12 @@ function scaffoldOptionalCodex(projectRoot) {
 }
 export function initRepository(projectRoot, options) {
     ensureDir(projectRoot);
+    migrateLegacyRootFiles(projectRoot);
     for (const deprecatedPath of [
         "docs/README.md",
         "docs/code-guide.md",
+        "docs/legacy-import",
+        "WAYPOINT_MIGRATION.md",
         ".agents/skills/waypoint-planning",
         ".agents/skills/waypoint-docs",
         ".agents/skills/waypoint-review",
@@ -138,9 +150,9 @@ export function initRepository(projectRoot, options) {
     return [
         "Initialized Waypoint scaffold",
         "Installed managed AGENTS block",
-        "Created WORKSPACE.md and .waypoint/docs/ scaffold",
+        "Created .waypoint/WORKSPACE.md and .waypoint/docs/ scaffold",
         "Installed repo-local Waypoint skills",
-        "Generated DOCS_INDEX.md",
+        "Generated .waypoint/DOCS_INDEX.md",
     ];
 }
 export function loadWaypointConfig(projectRoot) {
@@ -316,7 +328,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "error",
             category: "workspace",
-            message: "WORKSPACE.md is missing.",
+            message: ".waypoint/WORKSPACE.md is missing.",
             remediation: "Run `waypoint init` to scaffold the workspace file.",
             paths: [workspacePath],
         });
@@ -365,7 +377,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "error",
             category: "docs",
-            message: "docs/ directory is missing.",
+            message: ".waypoint/docs/ directory is missing.",
             remediation: "Run `waypoint init` to scaffold docs.",
             paths: [docsDir],
         });
@@ -383,7 +395,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "warn",
             category: "docs",
-            message: "DOCS_INDEX.md is missing.",
+            message: ".waypoint/DOCS_INDEX.md is missing.",
             remediation: "Run `waypoint sync` to generate the docs index.",
             paths: [docsIndexPath],
         });
@@ -392,7 +404,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "warn",
             category: "docs",
-            message: "DOCS_INDEX.md is stale.",
+            message: ".waypoint/DOCS_INDEX.md is stale.",
             remediation: "Run `waypoint sync` to rebuild the docs index.",
             paths: [docsIndexPath],
         });
@@ -472,7 +484,7 @@ export function syncRepository(projectRoot) {
     const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
     const docsIndex = renderDocsIndex(projectRoot, docsDir);
     writeText(docsIndexPath, `${docsIndex.content}\n`);
-    const results = ["Rebuilt DOCS_INDEX.md"];
+    const results = ["Rebuilt .waypoint/DOCS_INDEX.md"];
     const featureMap = config.features ?? {};
     if (featureMap.rules) {
         results.push(...syncRules(projectRoot));
@@ -527,7 +539,7 @@ export function importLegacyRepo(sourceRepo, targetRepo, options = {}) {
         }));
     }
     if (targetRepo) {
-        const importDir = path.join(targetRepo, "docs/legacy-import");
+        const importDir = path.join(targetRepo, ".waypoint/docs/legacy-import");
         ensureDir(importDir);
         for (const docName of portableDocs) {
             copyFileSync(path.join(sourceDocsDir, docName), path.join(importDir, docName));
@@ -585,7 +597,7 @@ export function importLegacyRepo(sourceRepo, targetRepo, options = {}) {
         "",
     ].join("\n");
     if (targetRepo) {
-        const reportPath = path.join(targetRepo, "WAYPOINT_MIGRATION.md");
+        const reportPath = path.join(targetRepo, ".waypoint/IMPORT_LEGACY.md");
         writeText(reportPath, report);
         actions.push(`Wrote migration report to ${reportPath}`);
     }

package/package.json

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

package/templates/.gitignore.snippet

@@ -1,3 +1,4 @@
 # Waypoint state
+.waypoint/DOCS_INDEX.md
 .waypoint/state/
 .waypoint/context/

package/templates/.waypoint/README.md

@@ -3,6 +3,8 @@
 Repo-local Waypoint configuration and optional integration sources.
 
 - `config.toml` — Waypoint feature toggles and file locations
+- `WORKSPACE.md` — live operational state
+- `DOCS_INDEX.md` — generated docs routing map
 - `SOUL.md` — agent identity and working values
 - `agent-operating-manual.md` — required session workflow
 - `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans)

package/templates/.waypoint/agent-operating-manual.md

@@ -9,7 +9,7 @@ At the start of every session:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
 3. Read this file
-4. Read `WORKSPACE.md`
+4. Read `.waypoint/WORKSPACE.md`
 5. Read `.waypoint/context/MANIFEST.md`
 6. Read every file listed in that manifest
 
@@ -19,7 +19,7 @@ Do not skip this sequence.
 
 The repository should contain the context the next agent needs.
 
-- `WORKSPACE.md` is the live operational record: in progress, current state, next steps
+- `.waypoint/WORKSPACE.md` is the live operational record: in progress, current state, next steps
 - `.waypoint/docs/` is the durable project memory: architecture, decisions, integration notes, debugging knowledge, and durable plans
 - `.waypoint/context/` is the generated session context bundle: current git/PR/doc index state
 
@@ -29,9 +29,9 @@ If something important lives only in your head or in the chat transcript, the re
 
 - Read code before editing it.
 - Follow the repo's documented patterns when they are healthy.
-- Update `WORKSPACE.md` as live execution state when progress meaningfully changes.
+- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes.
 - Update `.waypoint/docs/` when durable knowledge changes.
-- Rebuild `DOCS_INDEX.md` whenever routable docs change.
+- Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
 
 ## Documentation expectations

package/templates/.waypoint/config.toml

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

package/templates/.waypoint/scripts/build-docs-index.mjs

@@ -139,7 +139,7 @@ export function renderDocsIndex(projectRoot) {
 }
 
 export function writeDocsIndex(projectRoot) {
-  const outputPath = path.join(projectRoot, "DOCS_INDEX.md");
+  const outputPath = path.join(projectRoot, ".waypoint", "DOCS_INDEX.md");
   writeFileSync(outputPath, renderDocsIndex(projectRoot), "utf8");
   return outputPath;
 }

package/templates/.waypoint/scripts/prepare-context.mjs

@@ -388,7 +388,7 @@ function main() {
     "",
     "- `.waypoint/SOUL.md`",
     "- `.waypoint/agent-operating-manual.md`",
-    "- `WORKSPACE.md`",
+    "- `.waypoint/WORKSPACE.md`",
     "",
     `Generated by: \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\``,
     "",

package/templates/managed-agents-block.md

@@ -7,14 +7,14 @@ Before doing substantial work:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
 3. Read `.waypoint/agent-operating-manual.md`
-4. Read `WORKSPACE.md`
+4. Read `.waypoint/WORKSPACE.md`
 5. Read `.waypoint/context/MANIFEST.md`
 6. Read every file listed in the manifest
 
 This is mandatory, not optional. Do not skip the context refresh or skip files in the manifest.
 
 Working rules:
-- Keep `WORKSPACE.md` current as the live execution state
+- Keep `.waypoint/WORKSPACE.md` current as the live execution state
 - Update `.waypoint/docs/` when behavior or durable project knowledge changes
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
 - Treat the generated context bundle as required session bootstrap, not optional reference material