@ghl-ai/aw 0.1.25 → 0.1.26-beta.2

package/commands/init.mjs

@@ -218,7 +218,7 @@ export async function initCommand(args) {
 
     // Pull latest (parallel)
     // cfg.include has the renamed namespace (e.g. 'revex/courses'), but the repo
-    // only has 'registry/[template]/' — remap non-platform entries back.
+    // only has '.aw_registry/[template]/' — remap non-platform entries back.
     const freshCfg = config.load(GLOBAL_AW_DIR);
     if (freshCfg && freshCfg.include.length > 0) {
       const pullJobs = freshCfg.include.map(p => {

package/commands/pull.mjs

@@ -1,6 +1,6 @@
 // commands/pull.mjs — Pull content from registry
 
-import { mkdirSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
+import { mkdirSync, existsSync, readdirSync, copyFileSync, cpSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
@@ -8,6 +8,7 @@ import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
 import { sparseCheckout, sparseCheckoutAsync, cleanup, includeToSparsePaths } from '../git.mjs';
+import { REGISTRY_DIR } from '../constants.mjs';
 import { walkRegistryTree } from '../registry.mjs';
 import { matchesAny } from '../glob.mjs';
 import { computePlan } from '../plan.mjs';
@@ -111,7 +112,7 @@ export async function pullCommand(args) {
 
   try {
     const registryDirs = [];
-    const regBase = join(tempDir, 'registry');
+    const regBase = join(tempDir, REGISTRY_DIR);
 
     if (existsSync(regBase)) {
       for (const name of listDirs(regBase)) {
@@ -190,6 +191,16 @@ export async function pullCommand(args) {
       }
     }
 
+    // Bulk-copy docs/ directories (not a TYPE_DIR — raw recursive copy)
+    for (const rd of registryDirs) {
+      const docsDir = join(rd.path, 'docs');
+      if (existsSync(docsDir)) {
+        const dest = join(workspaceDir, rd.name, 'docs');
+        mkdirSync(dest, { recursive: true });
+        cpSync(docsDir, dest, { recursive: true });
+      }
+    }
+
     // MCP registration (second-class — skip if not available)
     if (cfg.namespace) {
       registerMcp(cfg.namespace);
@@ -235,7 +246,7 @@ export async function pullAsync(args) {
 
   try {
     const registryDirs = [];
-    const regBase = join(tempDir, 'registry');
+    const regBase = join(tempDir, REGISTRY_DIR);
 
     if (existsSync(regBase)) {
       for (const name of listDirs(regBase)) {
@@ -282,6 +293,16 @@ export async function pullAsync(args) {
       if (existsSync(src)) copyFileSync(src, join(workspaceDir, fname));
     }
 
+    // Bulk-copy docs/ directories (not a TYPE_DIR — raw recursive copy)
+    for (const rd of registryDirs) {
+      const docsDir = join(rd.path, 'docs');
+      if (existsSync(docsDir)) {
+        const dest = join(workspaceDir, rd.name, 'docs');
+        mkdirSync(dest, { recursive: true });
+        cpSync(docsDir, dest, { recursive: true });
+      }
+    }
+
     return { pattern, actions, conflictCount };
   } finally {
     cleanup(tempDir);

package/commands/push.mjs

@@ -6,7 +6,7 @@ import { execSync, execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_REPO, REGISTRY_BASE_BRANCH } from '../constants.mjs';
+import { REGISTRY_REPO, REGISTRY_BASE_BRANCH, REGISTRY_DIR } from '../constants.mjs';
 import { resolveInput } from '../paths.mjs';
 import { load as loadManifest } from '../manifest.mjs';
 import { hashFile } from '../registry.mjs';
@@ -98,8 +98,8 @@ export function pushCommand(args) {
 
   const isDir = statSync(absPath).isDirectory();
   const registryTarget = isDir
-    ? `registry/${namespacePath}/${parentDir}/${slug}`
-    : `registry/${namespacePath}/${parentDir}/${slug}.md`;
+    ? `${REGISTRY_DIR}/${namespacePath}/${parentDir}/${slug}`
+    : `${REGISTRY_DIR}/${namespacePath}/${parentDir}/${slug}.md`;
 
   fmt.note(
     [
@@ -148,13 +148,13 @@ export function pushCommand(args) {
 
     // Check if this is a new namespace — auto-add CODEOWNERS entry
     let newNamespace = false;
-    const nsDir = join(tempDir, 'registry', topNamespace);
+    const nsDir = join(tempDir, REGISTRY_DIR, topNamespace);
     const codeownersPath = join(tempDir, 'CODEOWNERS');
     if (!existsSync(nsDir) || isNewNamespaceInCodeowners(codeownersPath, topNamespace)) {
       newNamespace = true;
       const ghUser = getGitHubUser();
       if (ghUser && existsSync(codeownersPath)) {
-        const line = `/registry/${topNamespace}/ @${ghUser}\n`;
+        const line = `/${REGISTRY_DIR}/${topNamespace}/ @${ghUser}\n`;
         appendFileSync(codeownersPath, line);
         execSync('git add CODEOWNERS', { cwd: tempDir, stdio: 'pipe' });
       }
@@ -236,5 +236,5 @@ function getGitHubUser() {
 function isNewNamespaceInCodeowners(codeownersPath, namespace) {
   if (!existsSync(codeownersPath)) return true;
   const content = readFileSync(codeownersPath, 'utf8');
-  return !content.includes(`/registry/${namespace}/`);
+  return !content.includes(`/${REGISTRY_DIR}/${namespace}/`);
 }

package/commands/search.mjs

@@ -7,7 +7,7 @@ import { execSync } from 'node:child_process';
 import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_BASE_BRANCH, REGISTRY_REPO } from '../constants.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_REPO, REGISTRY_DIR } from '../constants.mjs';
 
 export function searchCommand(args) {
   const query = (args._positional || []).join(' ').toLowerCase();
@@ -150,14 +150,14 @@ function searchRemote(repo, query) {
     try {
       // git archive fetches a single file from remote — no clone needed
       content = execSync(
-        `git archive --remote="${repoUrl}" ${REGISTRY_BASE_BRANCH} registry/registry.json | tar -xO registry/registry.json`,
+        `git archive --remote="${repoUrl}" ${REGISTRY_BASE_BRANCH} ${REGISTRY_DIR}/registry.json | tar -xO ${REGISTRY_DIR}/registry.json`,
         { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
       );
     } catch {
       // GitHub doesn't support git archive — fallback to gh API
       try {
         const raw = execSync(
-          `gh api "repos/${repo}/contents/registry/registry.json?ref=${REGISTRY_BASE_BRANCH}" --jq .content -H "Accept: application/vnd.github.v3+json"`,
+          `gh api "repos/${repo}/contents/${REGISTRY_DIR}/registry.json?ref=${REGISTRY_BASE_BRANCH}" --jq .content -H "Accept: application/vnd.github.v3+json"`,
           { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
         );
         content = Buffer.from(raw.trim(), 'base64').toString('utf8');
@@ -167,9 +167,9 @@ function searchRemote(repo, query) {
         try {
           execSync(`git clone --filter=blob:none --no-checkout "${repoUrl}" "${tempDir}"`, { stdio: 'pipe' });
           execSync('git sparse-checkout init --cone', { cwd: tempDir, stdio: 'pipe' });
-          execSync('git sparse-checkout set --skip-checks "registry/registry.json"', { cwd: tempDir, stdio: 'pipe' });
+          execSync(`git sparse-checkout set --skip-checks "${REGISTRY_DIR}/registry.json"`, { cwd: tempDir, stdio: 'pipe' });
           execSync(`git checkout ${REGISTRY_BASE_BRANCH}`, { cwd: tempDir, stdio: 'pipe' });
-          content = readFileSync(join(tempDir, 'registry', 'registry.json'), 'utf8');
+          content = readFileSync(join(tempDir, REGISTRY_DIR, 'registry.json'), 'utf8');
         } finally {
           try { execSync(`rm -rf "${tempDir}"`, { stdio: 'pipe' }); } catch {}
         }

package/constants.mjs

@@ -1,7 +1,10 @@
 // constants.mjs — Single source of truth for registry settings.
 
 /** Base branch for PRs and sync checkout */
-export const REGISTRY_BASE_BRANCH = 'master';
+export const REGISTRY_BASE_BRANCH = 'feat/aw-platform-docs';
 
 /** Default registry repository */
-export const REGISTRY_REPO = 'GoHighLevel/ghl-agentic-workspace';
+export const REGISTRY_REPO = 'GoHighLevel/platform-docs';
+
+/** Directory inside the registry repo that holds platform/ and [template]/ */
+export const REGISTRY_DIR = '.aw_registry';

package/git.mjs

@@ -5,7 +5,7 @@ import { mkdtempSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { promisify } from 'node:util';
-import { REGISTRY_BASE_BRANCH } from './constants.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_DIR } from './constants.mjs';
 
 const exec = promisify(execCb);
 
@@ -76,16 +76,13 @@ export function cleanup(tempDir) {
 
 /**
  * Compute sparse checkout paths from include paths.
- * e.g., ["platform", "dev/agents/debugger"] -> ["registry/platform", "registry/dev/agents/debugger"]
+ * e.g., ["platform", "dev/agents/debugger"] -> [".aw_registry/platform", ".aw_registry/dev/agents/debugger"]
  */
 export function includeToSparsePaths(paths) {
   const result = new Set();
   for (const p of paths) {
-    result.add(`registry/${p}`);
+    result.add(`${REGISTRY_DIR}/${p}`);
   }
-  // Also fetch root instruction files
-  result.add('registry/CLAUDE.md');
-  result.add('registry/AGENTS.md');
-  result.add('registry/AW-PROTOCOL.md');
+  result.add(`${REGISTRY_DIR}/AW-PROTOCOL.md`);
   return [...result];
 }

package/integrate.mjs

@@ -65,7 +65,7 @@ export function copyInstructions(cwd, tempDir, namespace) {
     if (existsSync(dest)) continue;
 
     if (tempDir) {
-      const src = join(tempDir, 'registry', file);
+      const src = join(tempDir, '.aw_registry', file);
       if (existsSync(src)) {
         let content = readFileSync(src, 'utf8');
         if (namespace) {

package/link.mjs

@@ -1,15 +1,19 @@
 // link.mjs — Create symlinks from IDE dirs → .aw_registry/
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync, symlinkSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import * as fmt from './fmt.mjs';
 
+function forceSymlink(target, linkPath) {
+  try { unlinkSync(linkPath); } catch { /* not there yet */ }
+  symlinkSync(target, linkPath);
+}
+
 const IDE_DIRS = ['.claude', '.cursor', '.codex'];
 // Per-file symlink types
 const FILE_TYPES = ['agents'];
-const ALL_KNOWN_TYPES = new Set([...FILE_TYPES, 'skills', 'commands', 'evals']);
+const ALL_KNOWN_TYPES = new Set([...FILE_TYPES, 'skills', 'commands', 'evals', 'docs']);
 
 /**
  * List namespace directories inside .aw_registry/ (skip dotfiles).
@@ -135,10 +139,7 @@ export function linkWorkspace(cwd) {
             const linkPath = join(linkDir, flat);
             const targetPath = join(typeDirPath, file);
             const relTarget = relative(linkDir, targetPath);
-            try {
-              execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-              created++;
-            } catch { /* best effort */ }
+            try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
           }
         }
       }
@@ -155,10 +156,7 @@ export function linkWorkspace(cwd) {
           const linkPath = join(linkDir, flat);
           const targetPath = join(skillsDir, skill);
           const relTarget = relative(linkDir, targetPath);
-          try {
-            execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-            created++;
-          } catch { /* best effort */ }
+          try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
         }
       }
     }
@@ -178,10 +176,7 @@ export function linkWorkspace(cwd) {
             const linkPath = join(linkDir, flat);
             const targetPath = join(subDir, evalName);
             const relTarget = relative(linkDir, targetPath);
-            try {
-              execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-              created++;
-            } catch { /* best effort */ }
+            try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
           }
         }
       }
@@ -199,10 +194,7 @@ export function linkWorkspace(cwd) {
           const linkPath = join(agentsSkillsDir, flat);
           const targetPath = join(skillsDir, skill);
           const relTarget = relative(agentsSkillsDir, targetPath);
-          try {
-            execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-            created++;
-          } catch { /* best effort */ }
+          try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
         }
       }
     }
@@ -220,10 +212,7 @@ export function linkWorkspace(cwd) {
           const linkPath = join(linkDir, cmdFileName);
           const targetPath = join(commandsDir, file);
           const relTarget = relative(linkDir, targetPath);
-          try {
-            execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-            created++;
-          } catch { /* best effort */ }
+          try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
         }
       }
     }
@@ -235,13 +224,19 @@ export function linkWorkspace(cwd) {
     for (const ide of IDE_DIRS) {
       const linkPath = join(cwd, ide, 'AW-PROTOCOL.md');
       const relTarget = relative(join(cwd, ide), protocolSrc);
-      try {
-        if (existsSync(linkPath) || lstatSync(linkPath).isSymbolicLink()) unlinkSync(linkPath);
-      } catch { /* not there yet */ }
-      try {
-        execSync(`ln -sfn "${relTarget}" "${linkPath}"`, { stdio: 'pipe' });
-        created++;
-      } catch { /* best effort */ }
+      try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
+    }
+  }
+
+  // Docs: single directory symlink per IDE → .aw_registry/platform/docs
+  const platformDocsDir = join(awDir, 'platform', 'docs');
+  if (existsSync(platformDocsDir)) {
+    for (const ide of IDE_DIRS) {
+      const linkDir = join(cwd, ide);
+      mkdirSync(linkDir, { recursive: true });
+      const linkPath = join(linkDir, 'docs');
+      const relTarget = relative(linkDir, platformDocsDir);
+      try { forceSymlink(relTarget, linkPath); created++; } catch { /* best effort */ }
     }
   }
 

package/mcp.mjs

@@ -35,12 +35,12 @@ export function setupMcp(cwd, namespace) {
 
   const mcpUrl = paths.ghlMcpUrl;
 
-  const ghlAiServer = { type: 'url', url: mcpUrl };
+  const ghlAiServer = { type: 'http', url: mcpUrl };
   const gitJenkinsServer = paths.gitJenkinsPath
     ? { command: 'node', args: [paths.gitJenkinsPath] }
     : null;
 
-  // ── Claude Code: ~/.claude/settings.json ──
+  // ── Claude Code: ~/.claude/settings.json (global) ──
   const claudeSettingsPath = join(HOME, '.claude', 'settings.json');
   if (mergeJsonMcpServer(claudeSettingsPath, 'ghl-ai', ghlAiServer)) {
     updatedFiles.push(claudeSettingsPath);
@@ -49,7 +49,37 @@ export function setupMcp(cwd, namespace) {
     updatedFiles.push(claudeSettingsPath);
   }
 
-  // ── Cursor: ~/.cursor/mcp.json ──
+  // ── Claude Code: .mcp.json (project root — highest priority) ──
+  // Claude Code resolves project .mcp.json before global settings.json,
+  // so we must write here to ensure the HTTP URL takes precedence over
+  // any stale command-based configs in parent directories.
+  const projectMcpPath = join(cwd, '.mcp.json');
+  if (mergeJsonMcpServer(projectMcpPath, 'ghl-ai', ghlAiServer)) {
+    updatedFiles.push(projectMcpPath);
+  }
+
+  // ── Claude Code: .claude/mcp.json (workspace-level) ──
+  // Claude Code also reads .claude/mcp.json for workspace-scoped MCP config.
+  // Write here so the MCP server is available regardless of which resolution
+  // path Claude Code uses (root .mcp.json or .claude/mcp.json).
+  const claudeWorkspaceMcpPath = join(cwd, '.claude', 'mcp.json');
+  if (mergeJsonMcpServer(claudeWorkspaceMcpPath, 'ghl-ai', ghlAiServer)) {
+    updatedFiles.push(claudeWorkspaceMcpPath);
+  }
+  if (gitJenkinsServer && mergeJsonMcpServer(claudeWorkspaceMcpPath, 'git-jenkins', gitJenkinsServer)) {
+    updatedFiles.push(claudeWorkspaceMcpPath);
+  }
+
+  // ── Cursor: project .cursor/mcp.json (workspace-level) ──
+  const cursorProjectMcpPath = join(cwd, '.cursor', 'mcp.json');
+  if (mergeJsonMcpServer(cursorProjectMcpPath, 'ghl-ai', ghlAiServer)) {
+    updatedFiles.push(cursorProjectMcpPath);
+  }
+  if (gitJenkinsServer && mergeJsonMcpServer(cursorProjectMcpPath, 'git-jenkins', gitJenkinsServer)) {
+    updatedFiles.push(cursorProjectMcpPath);
+  }
+
+  // ── Cursor: ~/.cursor/mcp.json (global) ──
   const cursorMcpPath = join(HOME, '.cursor', 'mcp.json');
   if (mergeJsonMcpServer(cursorMcpPath, 'ghl-ai', ghlAiServer)) {
     updatedFiles.push(cursorMcpPath);
@@ -94,12 +124,18 @@ function mergeJsonMcpServer(filePath, serverName, serverConfig) {
     config.mcpServers = {};
   }
 
-  // Check if already configured with same URL
+  // Check if already configured with same config
   const existing = config.mcpServers[serverName];
   if (existing && JSON.stringify(existing) === JSON.stringify(serverConfig)) {
     return false;
   }
 
+  // If we're writing an HTTP URL server, remove any stale command-based config
+  // to prevent old local MCP servers from shadowing the remote one.
+  if (serverConfig.type === 'http' && existing && existing.command) {
+    fmt.logStep(`Replacing stale command-based '${serverName}' with HTTP URL`);
+  }
+
   config.mcpServers[serverName] = serverConfig;
 
   mkdirSync(join(filePath, '..'), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.25",
+  "version": "0.1.26-beta.2",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {

package/registry.mjs

@@ -5,6 +5,7 @@ import { join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 
 const TYPE_DIRS = new Set(['agents', 'skills', 'commands', 'evals']);
+const SKIP_DIRS = new Set(['docs']);
 
 export function sha256(content) {
   return createHash('sha256').update(content).digest('hex');
@@ -97,7 +98,7 @@ export function walkRegistryTree(baseDir, baseName) {
             });
           }
         }
-      } else if (entry.isDirectory()) {
+      } else if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
         recurse(fullPath, [...pathSegments, entry.name]);
       }
     }