[0.9.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

[0.8.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

[0.7.0] — 2026-04-16

Added

Phase 5: Multi-AI Platform Support (Complete Overhaul)

• Interactive platform selection in waymark init

  • Users choose: Claude (recommended) | GitHub Copilot CLI (experimental) | Both
  • Conditional setup: only configure selected platforms
  • Platform choices stored in waymark.config.json v2

• GitHub Copilot CLI support

  • Shell wrapper script for automatic CLI interception and logging
  • CLI commands appear in dashboard alongside MCP actions
  • Non-blocking logging (1-second timeout, never slows user)

• New documentation

  • Platform comparison matrix and roadmap (see docs/README_PLATFORMS.md)
  • Setup guide for GitHub Copilot CLI (see docs/COPILOT_CLI.md)
  • FAQ with 200+ questions and answers (see docs/FAQ.md)

Complete Architecture Improvements (Phases 1-4)

• Plan mode logging visibility (shows Waymark activity in Claude plan mode)
• Multi-project management (central registry, easy project switching)
• Dashboard optimization (10-50x faster queries, pagination for large datasets)
• Intelligent port lifecycle (automatic release when projects close)

Changed

• Config schema: v1 → v2 (auto-migration, fully backward compatible)
• Init command now interactive (choose your platform)
• Database: Added source column to distinguish CLI vs MCP actions
• Dashboard: Unified timeline for all AI agent actions

Fixed

• Auto-migration preserves existing Claude configurations
• Type safety for optional fields in database schema
• Non-blocking logging resilience (works even if Waymark server down)

✅ Production Ready: All 31 todos complete, 100% backward compatible, ready for immediate deployment.

[0.6.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.2] — 2026-04-06

Changed

• Dashboard now shows project name in the header. After running
  npx @way_marks/cli start, the dashboard title displays waymark — your-project
  instead of a generic "waymark". No configuration required — the name
  is derived automatically from the project directory.
• New API endpoint GET /api/project returns project metadata
  (projectName, port) for UI consumption.

[0.5.1] — 2026-04-06

Changed

• README and CHANGELOG updated with deprecation notice and migration
  steps for users coming from @shaifulshabuj-waymarks packages.
• No code changes — docs-only patch release.

[0.5.0] — 2026-04-06

⚠️ Package scope renamed in this release.
@shaifulshabuj-waymarks/cli and @shaifulshabuj-waymarks/server are now
deprecated on npm. Switch to @way_marks/cli and @way_marks/server.
See migration steps below.

Migration from @shaifulshabuj-waymarks

# 1. Uninstall old packages
npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server

# 2. Install new packages
npx @way_marks/cli init

# 3. Restart Claude Code

Re-running init also updates your Claude Desktop MCP config to the new
waymark-${projectName} key format required for multi-project support.

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

[0.8.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

[0.7.0] — 2026-04-16

Added

Phase 5: Multi-AI Platform Support (Complete Overhaul)

• Interactive platform selection in waymark init

  • Users choose: Claude (recommended) | GitHub Copilot CLI (experimental) | Both
  • Conditional setup: only configure selected platforms
  • Platform choices stored in waymark.config.json v2

• GitHub Copilot CLI support

  • Shell wrapper script for automatic CLI interception and logging
  • CLI commands appear in dashboard alongside MCP actions
  • Non-blocking logging (1-second timeout, never slows user)

• New documentation

  • Platform comparison matrix and roadmap (see README_PLATFORMS.md)
  • Setup guide for GitHub Copilot CLI (see COPILOT_CLI.md)
  • FAQ with 200+ questions and answers (see FAQ.md)

Complete Architecture Improvements (Phases 1-4)

• Plan mode logging visibility (shows Waymark activity in Claude plan mode)
• Multi-project management (central registry, easy project switching)
• Dashboard optimization (10-50x faster queries, pagination for large datasets)
• Intelligent port lifecycle (automatic release when projects close)

Changed

• Config schema: v1 → v2 (auto-migration, fully backward compatible)
• Init command now interactive (choose your platform)
• Database: Added source column to distinguish CLI vs MCP actions
• Dashboard: Unified timeline for all AI agent actions

Fixed

• Auto-migration preserves existing Claude configurations
• Type safety for optional fields in database schema
• Non-blocking logging resilience (works even if Waymark server down)

✅ Production Ready: All 31 todos complete, 100% backward compatible, ready for immediate deployment.

[0.6.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.2] — 2026-04-06

Changed

• Dashboard now shows project name in the header. After running
  npx @way_marks/cli start, the dashboard title displays waymark — your-project
  instead of a generic "waymark". No configuration required — the name
  is derived automatically from the project directory.
• New API endpoint GET /api/project returns project metadata
  (projectName, port) for UI consumption.

[0.5.1] — 2026-04-06

Changed

• README and CHANGELOG updated with deprecation notice and migration
  steps for users coming from @shaifulshabuj-waymarks packages.
• No code changes — docs-only patch release.

[0.5.0] — 2026-04-06

⚠️ Package scope renamed in this release.
@shaifulshabuj-waymarks/cli and @shaifulshabuj-waymarks/server are now
deprecated on npm. Switch to @way_marks/cli and @way_marks/server.
See migration steps below.

Migration from @shaifulshabuj-waymarks

# 1. Uninstall old packages
npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server

# 2. Install new packages
npx @way_marks/cli init

# 3. Restart Claude Code

Re-running init also updates your Claude Desktop MCP config to the new
waymark-${projectName} key format required for multi-project support.

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

[0.6.0] — 2026-04-16

Added

• (Add changes here)

Changed

• (Add changes here)

Fixed

• (Add changes here)

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.2] — 2026-04-06

Changed

• Dashboard now shows project name in the header. After running
  npx @way_marks/cli start, the dashboard title displays waymark — your-project
  instead of a generic "waymark". No configuration required — the name
  is derived automatically from the project directory.
• New API endpoint GET /api/project returns project metadata
  (projectName, port) for UI consumption.

[0.5.1] — 2026-04-06

Changed

• README and CHANGELOG updated with deprecation notice and migration
  steps for users coming from @shaifulshabuj-waymarks packages.
• No code changes — docs-only patch release.

[0.5.0] — 2026-04-06

⚠️ Package scope renamed in this release.
@shaifulshabuj-waymarks/cli and @shaifulshabuj-waymarks/server are now
deprecated on npm. Switch to @way_marks/cli and @way_marks/server.
See migration steps below.

Migration from @shaifulshabuj-waymarks

# 1. Uninstall old packages
npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server

# 2. Install new packages
npx @way_marks/cli init

# 3. Restart Claude Code

Re-running init also updates your Claude Desktop MCP config to the new
waymark-${projectName} key format required for multi-project support.

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.2] — 2026-04-06

Changed

• Dashboard now shows project name in the header. After running
  npx @way_marks/cli start, the dashboard title displays waymark — your-project
  instead of a generic "waymark". No configuration required — the name
  is derived automatically from the project directory.
• New API endpoint GET /api/project returns project metadata
  (projectName, port) for UI consumption.

[0.5.1] — 2026-04-06

Changed

• README and CHANGELOG updated with deprecation notice and migration
  steps for users coming from @shaifulshabuj-waymarks packages.
• No code changes — docs-only patch release.

[0.5.0] — 2026-04-06

⚠️ Package scope renamed in this release.
@shaifulshabuj-waymarks/cli and @shaifulshabuj-waymarks/server are now
deprecated on npm. Switch to @way_marks/cli and @way_marks/server.
See migration steps below.

Migration from @shaifulshabuj-waymarks

# 1. Uninstall old packages
npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server

# 2. Install new packages
npx @way_marks/cli init

# 3. Restart Claude Code

Re-running init also updates your Claude Desktop MCP config to the new
waymark-${projectName} key format required for multi-project support.

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.1] — 2026-04-06

Changed

• README and CHANGELOG updated with deprecation notice and migration
  steps for users coming from @shaifulshabuj-waymarks packages.
• No code changes — docs-only patch release.

[0.5.0] — 2026-04-06

⚠️ Package scope renamed in this release.
@shaifulshabuj-waymarks/cli and @shaifulshabuj-waymarks/server are now
deprecated on npm. Switch to @way_marks/cli and @way_marks/server.
See migration steps below.

Migration from @shaifulshabuj-waymarks

# 1. Uninstall old packages
npm uninstall @shaifulshabuj-waymarks/cli @shaifulshabuj-waymarks/server

# 2. Install new packages
npx @way_marks/cli init

# 3. Restart Claude Code

Re-running init also updates your Claude Desktop MCP config to the new
waymark-${projectName} key format required for multi-project support.

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.5.0] — 2026-04-06

Added

• Multi-project support: Each project now gets its own isolated SQLite database
  at .waymark/waymark.db, an auto-selected port (3001–3010), and a named MCP
  server entry (waymark-${projectName}) in Claude Desktop config. Multiple
  Waymark projects can run simultaneously without conflict.
• Port auto-selection: waymark start probes ports 3001–3010 and picks the
  first available one. Port is stored in .waymark/config.json.
• Project status command (waymark status): Shows project name, root, DB
  path, port, dashboard URL, MCP key, and whether the server is currently running.

Changed

• Package scope renamed from @shaifulshabuj-waymarks to @way_marks.
  Install with npm install @way_marks/server or npx @way_marks/cli init.
• CLAUDE.md template now uses mandatory enforcement language with exact MCP
  tool names (mcp__waymark-${projectName}__write_file, etc.) instead of polite
  suggestions. Claude Code will enforce Waymark tool usage without ambiguity.
• MCP server registration now uses waymark-${projectName} as the Claude
  Desktop config key instead of the generic "waymark". Re-run init in each
  project to register the updated key.

Fixed

• waymark init no longer overwrites other projects' MCP entries when registering
  a new project — it adds/updates only the current project's key.

Breaking changes

• DB location moved from data/waymark.db to .waymark/waymark.db.
  Existing databases are not migrated automatically.
• MCP key in Claude Desktop config changes. Re-run npx @way_marks/cli init
  in each project after upgrading.

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @way_marks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @way_marks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

Changelog

All notable changes to Waymark are documented here.
Format follows Keep a Changelog
Versioning follows Semantic Versioning

[0.4.0] — 2026-04-04

Fixed

• Security: Approving a pending write_file action now re-checks current policies
  before writing. If a policy was tightened after the action was queued, the approval
  is rejected with an explanation rather than silently executing.
• Security: Actions logged without an explicit policy decision no longer default
  to allow. The safe default is now pending.
• Behaviour: Paths listed in requireApproval no longer hold read_file actions
  pending. Read operations are idempotent — only writes require approval.
• Reliability: Bash command output is now capped at maxBashOutputBytes
  (default 10 000) with a [OUTPUT TRUNCATED] marker appended when the limit
  is exceeded.
• Compatibility: Node binary detection now uses process.execPath instead of
  reading NVM alias files. Works correctly with Homebrew, system Node, and any
  version manager.
• CLI: waymark logs no longer crashes on rows with malformed input_payload.
• CLI: Date display in waymark logs is now consistent regardless of whether
  the database stores timestamps with a space or a T separator.

[0.3.0] — 2026-04-04

CLI output fixes

• All command hints in CLI output now show the full
  npx @shaifulshabuj-waymarks/cli <cmd> form —
  works correctly whether Waymark is installed
  globally or invoked via npx

[0.2.0] — 2026-04-04

Background daemon mode

• waymark start now runs servers in the background and returns to prompt immediately — closing the terminal no longer stops Waymark
• Added waymark stop command for clean shutdown
• waymark status now detects crashed servers and cleans up stale PID files automatically

[0.1.0] — 2026-04-04

First public release

Core Features

• MCP server for native Claude Code integration
• Intercepts write_file, read_file, and bash actions
  in real time before execution
• Policy engine with four control types:
  allowedPaths, blockedPaths,
  blockedCommands, requireApproval
• Regex pattern support in blockedCommands
  for flexible command matching
• Rollback any write_file action to its
  previous state with one click
• Approve or reject pending actions
  from the web dashboard
• Slack webhook notifications for
  pending approval actions
• SQLite action ledger — every action logged
  with full context and agent reasoning

Developer Experience

• npx @shaifulshabuj-waymarks/cli init — one command project setup
• Auto-generates waymark.config.json
• Auto-generates CLAUDE.md for always-on
  Claude Code activation
• Auto-registers MCP server in Claude
  desktop config
• waymark start — launches dashboard
  and MCP server together
• waymark logs — terminal action viewer
  with --pending and --blocked filters
• waymark status — quick health check

Security

• Regex-based command blocking catches
  pipe-to-shell attacks (curl | bash variants)
• Default deny for paths not in allowedPaths
• blockedPaths take priority over allowedPaths
• Pending actions never execute without
  explicit human approval
• Double-approve and double-rollback guards

Waymark Changelog

This file documents every version of Waymark: what was built, what the original spec asked for, what broke during testing, and how it was fixed. Each entry is written so a human or AI agent can understand not just what changed but why.

v4.1 — Release Preparation & Package Naming (2026-04-04)

What was built

Prepared the monorepo for public release to waymarks/waymark (GitHub) and npm. No application code changed — only release infrastructure, package metadata, and naming fixes.

New files: LICENSE, .env.example, .github/workflows/release.yml, .github/workflows/ci.yml, scripts/pre-release-check.sh, release/README.md, release/CHANGELOG.md.

Modified files: packages/cli/package.json (name, author, license, homepage, repository, bugs, keywords, dependencies), packages/server/package.json (name, description, author, license, homepage, repository, bugs, keywords), packages/cli/src/commands/start.ts (package reference fix), packages/cli/src/commands/init.ts (package reference fixes, 6 occurrences), .gitignore (expanded), release.yml (copy from release/ not root).

Issue 1 — npx waymark package name conflict

Symptom: npm view waymark returned an existing deprecated React router package ([email protected]). Publishing under the name waymark would silently conflict or fail.

Root cause: The unscoped waymark name on npm was already registered. v4.0 had planned to publish as waymark for clean npx waymark init UX.

Fix: Renamed CLI package from "waymark" to "@shaifulshabuj-waymarks/cli". Updated all npx waymark references across release/README.md, release/CHANGELOG.md, README.md, packages/cli/src/commands/init.ts, and dev CHANGELOG.md to npx @shaifulshabuj-waymarks/cli.

The bin entry stays "waymark": "./dist/index.js" — so after install, the CLI command is still waymark start, waymark logs etc. Only the initial npx invocation uses the scoped name.

Issue 2 — Stale @shaifulshabuj-waymarks/server package reference in CLI

Symptom: start.ts and init.ts still referenced @shaifulshabuj-waymarks/server (old name) inside require.resolve() calls. During the rename phase from @waymarks/server back to @shaifulshabuj-waymarks/server, start.ts was fixed but init.ts had 5 additional occurrences that were missed.

Root cause: grep was not run across all CLI source files before closing out the rename. Only start.ts was checked.

Fix: Ran grep -r "@waymarks/" across the full workspace, found 11 occurrences in 4 files, updated all in one pass.

Files fixed:

• packages/server/package.json — name field
• packages/cli/package.json — dependencies entry
• packages/cli/src/commands/start.ts — require.resolve path
• packages/cli/src/commands/init.ts — require.resolve (2×), console.log messages (3×), spawnSync install arg (1×)

Issue 3 — @shaifulshabuj-waymarks/server missing from CLI dependencies

Symptom: packages/cli/package.json had zero dependencies. When a user runs npx @shaifulshabuj-waymarks/cli start, npm downloads and executes the CLI package in isolation — @shaifulshabuj-waymarks/server would not be present, causing require.resolve('@shaifulshabuj-waymarks/server/dist/...') to throw and fall back to a monorepo-relative path that doesn't exist outside dev.

Root cause: The CLI was designed with zero runtime deps, but @shaifulshabuj-waymarks/server is a required runtime peer — the CLI spawns its processes.

Fix: Added "dependencies": { "@shaifulshabuj-waymarks/server": "0.1.0" } to packages/cli/package.json. npm now installs both packages together when a user runs npx @shaifulshabuj-waymarks/cli.

Issue 4 — Public and dev docs mixed in repo root

Symptom: README.md and CHANGELOG.md at the repo root contained dev-focused documentation (architecture, database schema, for-AI-agents notes, full bug history). The release pipeline (release.yml) was copying these directly to waymarks/waymark (public repo), exposing internal dev notes publicly.

Root cause: Release pipeline used cp README.md /tmp/release/ and cp CHANGELOG.md /tmp/release/ without any distinction between dev and public content.

Fix:

1. Created release/ directory with separate public-facing versions:
   • release/README.md — user-facing README (install, config, CLI, Slack, roadmap)
   • release/CHANGELOG.md — public v0.1.0 entry (Core Features, Developer Experience, Security)
2. Restored root README.md and CHANGELOG.md to dev versions via git checkout HEAD
3. Updated release.yml copy step:

   - cp README.md /tmp/release/
   - cp CHANGELOG.md /tmp/release/
   + cp release/README.md /tmp/release/README.md
   + cp release/CHANGELOG.md /tmp/release/CHANGELOG.md

release/ is committed to the private dev repo — GitHub Actions reads from it at release time. It never appears in the public repo output.

Issue 5 — Org scope vs app name naming inconsistency

Symptom: During initial release prep, server package was renamed @waymarks/server (plural, matching GitHub org waymarks). CLI was named @waymarks/cli. But application and npm package convention uses the app name waymark (singular) as scope.

Root cause: Confusion between GitHub org name (waymarks) and npm package scope convention (@waymark). The org is waymarks; the product is waymark.

Fix: Renamed all packages to use @shaifulshabuj-waymarks/ scope:

• @waymarks/cli → @shaifulshabuj-waymarks/cli
• @waymarks/server → @shaifulshabuj-waymarks/server

The GitHub org waymarks remains for the public repo URL (github.com/waymarks/waymark). The npm scope @shaifulshabuj-waymarks is separate from the GitHub org name.

Release pipeline design

Two-repo strategy: Private dev repo (shaifulshabuj/waymark) triggers the release. Public repo (waymarks/waymark) receives the output. Users interact only with the public repo and npm packages.

Trigger: Push a git tag starting with v to the private repo:

git tag v0.1.0
git push origin v0.1.0

Pipeline steps (.github/workflows/release.yml):

1. npm install + npm run build --workspaces — compiles TypeScript in both packages
2. Clone waymarks/waymark → rsync compiled packages/ + copy release/README.md, release/CHANGELOG.md, LICENSE, package.json, .gitignore, .env.example
3. Commit + tag + push to public repo under the same tag name
4. npm publish @shaifulshabuj-waymarks/cli --access public
5. npm publish @shaifulshabuj-waymarks/server --access public
6. Create GitHub Release on waymarks/waymark using release/CHANGELOG.md

Both repos get the tag: Private repo gets it first (you push it to trigger CI). Public repo gets it from the pipeline. This is intentional — the public tag is what users see on github.com/waymarks/waymark/releases.

Required secrets (in shaifulshabuj/waymark → Settings → Secrets):

• NPM_TOKEN — npm access token with publish rights for the @shaifulshabuj-waymarks scope
• RELEASE_REPO_TOKEN — GitHub fine-grained PAT with Contents write on waymarks/waymark

CI pipeline (.github/workflows/ci.yml): Runs on every push to main and every PR. Steps: install, build, secrets scan (grep for sk-ant, ANTHROPIC_API_KEY, hardcoded npm tokens in source files). Fails the PR if any are found.

Pre-release check script (scripts/pre-release-check.sh): Local sanity check before tagging. Verifies .env not git-tracked, no .db files committed, no obvious secrets in git history, build passes, all required release files exist. Run manually before git tag.

Acceptance tests (all pass)

What was built

Restructured the project as an npm workspaces monorepo with two packages: @waymark/server (the existing MCP + API server, moved from src/ to packages/server/src/) and @waymark/cli (new package providing waymark init, start, status, and logs commands via npx @waymark/cli).

This eliminates the two adoption blockers from v3.1:

1. Claude didn't automatically use Waymark tools — fixed by waymark init creating CLAUDE.md with instructions that Claude Code reads on project open
2. Setup required manual JSON editing of Claude config files — fixed by waymark init writing both Claude Desktop and .mcp.json configs automatically

New files: packages/cli/package.json, packages/cli/tsconfig.json, packages/cli/src/index.ts, packages/cli/src/commands/init.ts, packages/cli/src/commands/start.ts, packages/cli/src/commands/status.ts, packages/cli/src/commands/logs.ts, packages/server/package.json, packages/server/tsconfig.json.

Moved files: src/ → packages/server/src/, tsconfig.json → packages/server/tsconfig.json.

Modified files: package.json (workspace root), packages/server/src/db/database.ts (WAYMARK_PROJECT_ROOT), packages/server/src/policies/engine.ts (WAYMARK_PROJECT_ROOT), packages/server/src/mcp/server.ts (--project-root arg parse at top), .mcp.json (updated path), .claude/launch.json (updated path...

Waymark Changelog

This file documents every version of Waymark: what was built, what the original spec asked for, what broke during testing, and how it was fixed. Each entry is written so a human or AI agent can understand not just what changed but why.

v4.1 — Release Preparation & Package Naming (2026-04-04)

What was built

Prepared the monorepo for public release to waymarks/waymark (GitHub) and npm. No application code changed — only release infrastructure, package metadata, and naming fixes.

New files: LICENSE, .env.example, .github/workflows/release.yml, .github/workflows/ci.yml, scripts/pre-release-check.sh, release/README.md, release/CHANGELOG.md.

Modified files: packages/cli/package.json (name, author, license, homepage, repository, bugs, keywords, dependencies), packages/server/package.json (name, description, author, license, homepage, repository, bugs, keywords), packages/cli/src/commands/start.ts (package reference fix), packages/cli/src/commands/init.ts (package reference fixes, 6 occurrences), .gitignore (expanded), release.yml (copy from release/ not root).

Issue 1 — npx waymark package name conflict

Symptom: npm view waymark returned an existing deprecated React router package ([email protected]). Publishing under the name waymark would silently conflict or fail.

Root cause: The unscoped waymark name on npm was already registered. v4.0 had planned to publish as waymark for clean npx waymark init UX.

Fix: Renamed CLI package from "waymark" to "@shaifulshabuj-waymarks/cli". Updated all npx waymark references across release/README.md, release/CHANGELOG.md, README.md, packages/cli/src/commands/init.ts, and dev CHANGELOG.md to npx @shaifulshabuj-waymarks/cli.

The bin entry stays "waymark": "./dist/index.js" — so after install, the CLI command is still waymark start, waymark logs etc. Only the initial npx invocation uses the scoped name.

Issue 2 — Stale @shaifulshabuj-waymarks/server package reference in CLI

Symptom: start.ts and init.ts still referenced @shaifulshabuj-waymarks/server (old name) inside require.resolve() calls. During the rename phase from @waymarks/server back to @shaifulshabuj-waymarks/server, start.ts was fixed but init.ts had 5 additional occurrences that were missed.

Root cause: grep was not run across all CLI source files before closing out the rename. Only start.ts was checked.

Fix: Ran grep -r "@waymarks/" across the full workspace, found 11 occurrences in 4 files, updated all in one pass.

Files fixed:

• packages/server/package.json — name field
• packages/cli/package.json — dependencies entry
• packages/cli/src/commands/start.ts — require.resolve path
• packages/cli/src/commands/init.ts — require.resolve (2×), console.log messages (3×), spawnSync install arg (1×)

Issue 3 — @shaifulshabuj-waymarks/server missing from CLI dependencies

Symptom: packages/cli/package.json had zero dependencies. When a user runs npx @shaifulshabuj-waymarks/cli start, npm downloads and executes the CLI package in isolation — @shaifulshabuj-waymarks/server would not be present, causing require.resolve('@shaifulshabuj-waymarks/server/dist/...') to throw and fall back to a monorepo-relative path that doesn't exist outside dev.

Root cause: The CLI was designed with zero runtime deps, but @shaifulshabuj-waymarks/server is a required runtime peer — the CLI spawns its processes.

Fix: Added "dependencies": { "@shaifulshabuj-waymarks/server": "0.1.0" } to packages/cli/package.json. npm now installs both packages together when a user runs npx @shaifulshabuj-waymarks/cli.

Issue 4 — Public and dev docs mixed in repo root

Symptom: README.md and CHANGELOG.md at the repo root contained dev-focused documentation (architecture, database schema, for-AI-agents notes, full bug history). The release pipeline (release.yml) was copying these directly to waymarks/waymark (public repo), exposing internal dev notes publicly.

Root cause: Release pipeline used cp README.md /tmp/release/ and cp CHANGELOG.md /tmp/release/ without any distinction between dev and public content.

Fix:

1. Created release/ directory with separate public-facing versions:
   • release/README.md — user-facing README (install, config, CLI, Slack, roadmap)
   • release/CHANGELOG.md — public v0.1.0 entry (Core Features, Developer Experience, Security)
2. Restored root README.md and CHANGELOG.md to dev versions via git checkout HEAD
3. Updated release.yml copy step:

   - cp README.md /tmp/release/
   - cp CHANGELOG.md /tmp/release/
   + cp release/README.md /tmp/release/README.md
   + cp release/CHANGELOG.md /tmp/release/CHANGELOG.md

release/ is committed to the private dev repo — GitHub Actions reads from it at release time. It never appears in the public repo output.

Issue 5 — Org scope vs app name naming inconsistency

Symptom: During initial release prep, server package was renamed @waymarks/server (plural, matching GitHub org waymarks). CLI was named @waymarks/cli. But application and npm package convention uses the app name waymark (singular) as scope.

Root cause: Confusion between GitHub org name (waymarks) and npm package scope convention (@waymark). The org is waymarks; the product is waymark.

Fix: Renamed all packages to use @shaifulshabuj-waymarks/ scope:

• @waymarks/cli → @shaifulshabuj-waymarks/cli
• @waymarks/server → @shaifulshabuj-waymarks/server

The GitHub org waymarks remains for the public repo URL (github.com/waymarks/waymark). The npm scope @shaifulshabuj-waymarks is separate from the GitHub org name.

Release pipeline design

Two-repo strategy: Private dev repo (shaifulshabuj/waymark) triggers the release. Public repo (waymarks/waymark) receives the output. Users interact only with the public repo and npm packages.

Trigger: Push a git tag starting with v to the private repo:

git tag v0.1.0
git push origin v0.1.0

Pipeline steps (.github/workflows/release.yml):

1. npm install + npm run build --workspaces — compiles TypeScript in both packages
2. Clone waymarks/waymark → rsync compiled packages/ + copy release/README.md, release/CHANGELOG.md, LICENSE, package.json, .gitignore, .env.example
3. Commit + tag + push to public repo under the same tag name
4. npm publish @shaifulshabuj-waymarks/cli --access public
5. npm publish @shaifulshabuj-waymarks/server --access public
6. Create GitHub Release on waymarks/waymark using release/CHANGELOG.md

Both repos get the tag: Private repo gets it first (you push it to trigger CI). Public repo gets it from the pipeline. This is intentional — the public tag is what users see on github.com/waymarks/waymark/releases.

Required secrets (in shaifulshabuj/waymark → Settings → Secrets):

• NPM_TOKEN — npm access token with publish rights for the @shaifulshabuj-waymarks scope
• RELEASE_REPO_TOKEN — GitHub fine-grained PAT with Contents write on waymarks/waymark

CI pipeline (.github/workflows/ci.yml): Runs on every push to main and every PR. Steps: install, build, secrets scan (grep for sk-ant, ANTHROPIC_API_KEY, hardcoded npm tokens in source files). Fails the PR if any are found.

Pre-release check script (scripts/pre-release-check.sh): Local sanity check before tagging. Verifies .env not git-tracked, no .db files committed, no obvious secrets in git history, build passes, all required release files exist. Run manually before git tag.

Acceptance tests (all pass)

What was built

Restructured the project as an npm workspaces monorepo with two packages: @waymark/server (the existing MCP + API server, moved from src/ to packages/server/src/) and @waymark/cli (new package providing waymark init, start, status, and logs commands via npx @waymark/cli).

This eliminates the two adoption blockers from v3.1:

1. Claude didn't automatically use Waymark tools — fixed by waymark init creating CLAUDE.md with instructions that Claude Code reads on project open
2. Setup required manual JSON editing of Claude config files — fixed by waymark init writing both Claude Desktop and .mcp.json configs automatically

New files: packages/cli/package.json, packages/cli/tsconfig.json, packages/cli/src/index.ts, packages/cli/src/commands/init.ts, packages/cli/src/commands/start.ts, packages/cli/src/commands/status.ts, packages/cli/src/commands/logs.ts, packages/server/package.json, packages/server/tsconfig.json.

Moved files: src/ → packages/server/src/, tsconfig.json → packages/server/tsconfig.json.

Modified files: package.json (workspace root), packages/server/src/db/database.ts (WAYMARK_PROJECT_ROOT), packages/server/src/policies/engine.ts (WAYMARK_PROJECT_ROOT), packages/server/src/mcp/server.ts (--project-root arg parse at top), .mcp.json (updated path), .claude/launch.json (updated path...

Waymark Changelog

This file documents every version of Waymark: what was built, what the original spec asked for, what broke during testing, and how it was fixed. Each entry is written so a human or AI agent can understand not just what changed but why.

v4.1 — Release Preparation & Package Naming (2026-04-04)

What was built

Prepared the monorepo for public release to waymarks/waymark (GitHub) and npm. No application code changed — only release infrastructure, package metadata, and naming fixes.

New files: LICENSE, .env.example, .github/workflows/release.yml, .github/workflows/ci.yml, scripts/pre-release-check.sh, release/README.md, release/CHANGELOG.md.

Modified files: packages/cli/package.json (name, author, license, homepage, repository, bugs, keywords, dependencies), packages/server/package.json (name, description, author, license, homepage, repository, bugs, keywords), packages/cli/src/commands/start.ts (package reference fix), packages/cli/src/commands/init.ts (package reference fixes, 6 occurrences), .gitignore (expanded), release.yml (copy from release/ not root).

Issue 1 — npx waymark package name conflict

Symptom: npm view waymark returned an existing deprecated React router package ([email protected]). Publishing under the name waymark would silently conflict or fail.

Root cause: The unscoped waymark name on npm was already registered. v4.0 had planned to publish as waymark for clean npx waymark init UX.

Fix: Renamed CLI package from "waymark" to "@waymark/cli". Updated all npx waymark references across release/README.md, release/CHANGELOG.md, README.md, packages/cli/src/commands/init.ts, and dev CHANGELOG.md to npx @waymark/cli.

The bin entry stays "waymark": "./dist/index.js" — so after install, the CLI command is still waymark start, waymark logs etc. Only the initial npx invocation uses the scoped name.

Issue 2 — Stale @waymark/server package reference in CLI

Symptom: start.ts and init.ts still referenced @waymark/server (old name) inside require.resolve() calls. During the rename phase from @waymarks/server back to @waymark/server, start.ts was fixed but init.ts had 5 additional occurrences that were missed.

Root cause: grep was not run across all CLI source files before closing out the rename. Only start.ts was checked.

Fix: Ran grep -r "@waymarks/" across the full workspace, found 11 occurrences in 4 files, updated all in one pass.

Files fixed:

• packages/server/package.json — name field
• packages/cli/package.json — dependencies entry
• packages/cli/src/commands/start.ts — require.resolve path
• packages/cli/src/commands/init.ts — require.resolve (2×), console.log messages (3×), spawnSync install arg (1×)

Issue 3 — @waymark/server missing from CLI dependencies

Symptom: packages/cli/package.json had zero dependencies. When a user runs npx @waymark/cli start, npm downloads and executes the CLI package in isolation — @waymark/server would not be present, causing require.resolve('@waymark/server/dist/...') to throw and fall back to a monorepo-relative path that doesn't exist outside dev.

Root cause: The CLI was designed with zero runtime deps, but @waymark/server is a required runtime peer — the CLI spawns its processes.

Fix: Added "dependencies": { "@waymark/server": "0.1.0" } to packages/cli/package.json. npm now installs both packages together when a user runs npx @waymark/cli.

Issue 4 — Public and dev docs mixed in repo root

Symptom: README.md and CHANGELOG.md at the repo root contained dev-focused documentation (architecture, database schema, for-AI-agents notes, full bug history). The release pipeline (release.yml) was copying these directly to waymarks/waymark (public repo), exposing internal dev notes publicly.

Root cause: Release pipeline used cp README.md /tmp/release/ and cp CHANGELOG.md /tmp/release/ without any distinction between dev and public content.

Fix:

1. Created release/ directory with separate public-facing versions:
   • release/README.md — user-facing README (install, config, CLI, Slack, roadmap)
   • release/CHANGELOG.md — public v0.1.0 entry (Core Features, Developer Experience, Security)
2. Restored root README.md and CHANGELOG.md to dev versions via git checkout HEAD
3. Updated release.yml copy step:

   - cp README.md /tmp/release/
   - cp CHANGELOG.md /tmp/release/
   + cp release/README.md /tmp/release/README.md
   + cp release/CHANGELOG.md /tmp/release/CHANGELOG.md

release/ is committed to the private dev repo — GitHub Actions reads from it at release time. It never appears in the public repo output.

Issue 5 — Org scope vs app name naming inconsistency

Symptom: During initial release prep, server package was renamed @waymarks/server (plural, matching GitHub org waymarks). CLI was named @waymarks/cli. But application and npm package convention uses the app name waymark (singular) as scope.

Root cause: Confusion between GitHub org name (waymarks) and npm package scope convention (@waymark). The org is waymarks; the product is waymark.

Fix: Renamed all packages to use @waymark/ scope:

• @waymarks/cli → @waymark/cli
• @waymarks/server → @waymark/server

The GitHub org waymarks remains for the public repo URL (github.com/waymarks/waymark). The npm scope @waymark is separate from the GitHub org name.

Release pipeline design

Two-repo strategy: Private dev repo (shaifulshabuj/waymark) triggers the release. Public repo (waymarks/waymark) receives the output. Users interact only with the public repo and npm packages.

Trigger: Push a git tag starting with v to the private repo:

git tag v0.1.0
git push origin v0.1.0

Pipeline steps (.github/workflows/release.yml):

1. npm install + npm run build --workspaces — compiles TypeScript in both packages
2. Clone waymarks/waymark → rsync compiled packages/ + copy release/README.md, release/CHANGELOG.md, LICENSE, package.json, .gitignore, .env.example
3. Commit + tag + push to public repo under the same tag name
4. npm publish @waymark/cli --access public
5. npm publish @waymark/server --access public
6. Create GitHub Release on waymarks/waymark using release/CHANGELOG.md

Both repos get the tag: Private repo gets it first (you push it to trigger CI). Public repo gets it from the pipeline. This is intentional — the public tag is what users see on github.com/waymarks/waymark/releases.

Required secrets (in shaifulshabuj/waymark → Settings → Secrets):

• NPM_TOKEN — npm access token with publish rights for the @waymark scope
• RELEASE_REPO_TOKEN — GitHub fine-grained PAT with Contents write on waymarks/waymark

CI pipeline (.github/workflows/ci.yml): Runs on every push to main and every PR. Steps: install, build, secrets scan (grep for sk-ant, ANTHROPIC_API_KEY, hardcoded npm tokens in source files). Fails the PR if any are found.

Pre-release check script (scripts/pre-release-check.sh): Local sanity check before tagging. Verifies .env not git-tracked, no .db files committed, no obvious secrets in git history, build passes, all required release files exist. Run manually before git tag.

Acceptance tests (all pass)

What was built

Restructured the project as an npm workspaces monorepo with two packages: @waymark/server (the existing MCP + API server, moved from src/ to packages/server/src/) and @waymark/cli (new package providing waymark init, start, status, and logs commands via npx @waymark/cli).

This eliminates the two adoption blockers from v3.1:

1. Claude didn't automatically use Waymark tools — fixed by waymark init creating CLAUDE.md with instructions that Claude Code reads on project open
2. Setup required manual JSON editing of Claude config files — fixed by waymark init writing both Claude Desktop and .mcp.json configs automatically

New files: packages/cli/package.json, packages/cli/tsconfig.json, packages/cli/src/index.ts, packages/cli/src/commands/init.ts, packages/cli/src/commands/start.ts, packages/cli/src/commands/status.ts, packages/cli/src/commands/logs.ts, packages/server/package.json, packages/server/tsconfig.json.

Moved files: src/ → packages/server/src/, tsconfig.json → packages/server/tsconfig.json.

Modified files: package.json (workspace root), packages/server/src/db/database.ts (WAYMARK_PROJECT_ROOT), packages/server/src/policies/engine.ts (WAYMARK_PROJECT_ROOT), packages/server/src/mcp/server.ts (--project-root arg parse at top), .mcp.json (updated path), .claude/launch.json (updated path), .claude/settings.json (updated hook paths).

Original spec prompt

Waymark v3.1 works correctly but has two adoption blockers.
Fix both. No new features.

Blocker 1: Claude doesn't automatically use Waymark tools

Claude needs to be told "use Waymark tools instead of direct file tools" in every new session.
This breaks the core value...