@ghl-ai/aw 0.1.50 → 0.1.51

package/cli.mjs

@@ -50,6 +50,9 @@ function parseArgs(argv) {
     if (arg === '--dry-run') {
       args['--dry-run'] = true;
       i++;
+    } else if (arg === '--aw-docs-only' || arg === '--docs-only') {
+      args[arg] = true;
+      i++;
     } else if (arg === '-v' || arg === '--verbose') {
       args['-v'] = true;
       i++;
@@ -97,6 +100,8 @@ function printHelp() {
 
     sec('Upload'),
     cmd('aw push', 'Push all modified files (creates one PR)'),
+    cmd('aw push --aw-docs-only', 'Publish generated .aw_docs companions and print share links'),
+    cmd('aw push --aw-docs-only --feature <slug>', 'Publish one .aw_docs feature folder and print share links'),
     cmd('aw push <path>', 'Push file, folder, or namespace to registry'),
     cmd('aw push-rules [path]', 'Push platform rules to platform-docs'),
     cmd('aw push --dry-run [path]', 'Preview what would be pushed'),

package/commands/push.mjs

@@ -1,17 +1,46 @@
 // commands/push.mjs — Push local agents/skills to registry via PR using persistent git clone
 
-import { existsSync, statSync, readFileSync, appendFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import {
+  existsSync,
+  lstatSync,
+  statSync,
+  readFileSync,
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  copyFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { exec as execCb, execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 const exec = promisify(execCb);
 const execFile = promisify(execFileCb);
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_REPO, REGISTRY_URL, REGISTRY_BASE_BRANCH, REGISTRY_DIR, AW_CO_AUTHOR } from '../constants.mjs';
+import {
+  REGISTRY_REPO,
+  REGISTRY_URL,
+  REGISTRY_BASE_BRANCH,
+  REGISTRY_DIR,
+  DOCS_SOURCE_DIR,
+  AW_DOCS_DIR,
+  AW_DOCS_REPO,
+  AW_DOCS_URL,
+  AW_DOCS_BASE_BRANCH,
+  AW_DOCS_SEED_BRANCH,
+  AW_DOCS_PUBLISH_DIR,
+  AW_DOCS_PUBLIC_BASE_URL,
+  AW_DOCS_TEAMOFONE_ORIGIN,
+  AW_DOCS_TEAMOFONE_BASE_URL,
+  AW_CO_AUTHOR,
+  defaultAwDocsGithubDocsConfig,
+} from '../constants.mjs';
 import { resolveInput } from '../paths.mjs';
 import { walkRegistryTree, getAllFiles } from '../registry.mjs';
 import {
@@ -21,6 +50,7 @@ import {
   checkoutMain,
   isValidClone,
   getLocalRegistryDir,
+  findNearestWorktree,
   commitsAheadOfMain,
   logAheadOfMain,
 } from '../git.mjs';
@@ -30,13 +60,612 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
 
 const PUSHABLE_TYPES = ['agents', 'skills', 'commands', 'evals', 'references'];
+const EXTRA_PUSH_PATHS = [DOCS_SOURCE_DIR, 'CODEOWNERS'];
+const EXTRA_PUSH_PATHS_ARG = EXTRA_PUSH_PATHS.map(p => `"${p}"`).join(' ');
+const PROJECT_AW_DOCS_AUTO_ROOTS = ['features', 'html'];
+
+function isAwDocsPath(p) {
+  return p === AW_DOCS_DIR || p.startsWith(`${AW_DOCS_DIR}/`);
+}
+
+function isContentPath(p) {
+  return p === DOCS_SOURCE_DIR || p.startsWith(`${DOCS_SOURCE_DIR}/`);
+}
+
+function managedPathSummary(paths) {
+  const unique = [...new Set(paths)];
+  const counts = {
+    awDocs: unique.filter(isAwDocsPath).length,
+    content: unique.filter(isContentPath).length,
+    codeowners: unique.filter(p => p === 'CODEOWNERS').length,
+  };
+  const known = counts.awDocs + counts.content + counts.codeowners;
+  const other = unique.length - known;
+  const parts = [];
+  if (counts.awDocs) parts.push(`${counts.awDocs} AW doc${counts.awDocs > 1 ? 's' : ''}`);
+  if (counts.content) parts.push(`${counts.content} platform doc${counts.content > 1 ? 's' : ''}`);
+  if (counts.codeowners) parts.push('CODEOWNERS');
+  if (other) parts.push(`${other} managed file${other > 1 ? 's' : ''}`);
+  return parts.join(', ') || 'managed files';
+}
+
+function managedBranchPrefix(paths) {
+  const unique = [...new Set(paths)];
+  if (unique.length > 0 && unique.every(isAwDocsPath)) return 'sync/aw-docs';
+  if (unique.length > 0 && unique.every(isContentPath)) return 'sync/platform-docs';
+  return 'sync/managed-docs';
+}
+
+function managedPrTitle(paths) {
+  const unique = [...new Set(paths)];
+  if (unique.length > 0 && unique.every(isAwDocsPath)) return 'docs(aw): sync AW docs';
+  if (unique.length > 0 && unique.every(isContentPath)) return 'docs(platform): sync platform docs';
+  return 'docs(aw): sync managed docs';
+}
+
+function formatManagedPathList(paths) {
+  const unique = [...new Set(paths)];
+  const lines = unique.slice(0, 40).map(p => `- \`${p}\``);
+  if (unique.length > 40) lines.push(`- ...and ${unique.length - 40} more`);
+  return lines;
+}
+
+function parseExtraStatusPaths(stdout) {
+  const paths = [];
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    const status = line.slice(0, 2);
+    const path = line.slice(2).trimStart();
+    if (!path) continue;
+    if (status === '!!' && !isAwDocsPath(path)) continue;
+    paths.push(path);
+  }
+  return [...new Set(paths)];
+}
+
+function getProjectRoot(cwd, home) {
+  if (existsSync(join(cwd, AW_DOCS_DIR))) return cwd;
+  const worktree = findNearestWorktree(cwd, home);
+  return worktree ? dirname(worktree) : cwd;
+}
+
+function collectFiles(root, base = root) {
+  if (!existsSync(root)) return [];
+
+  const files = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const fullPath = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(fullPath, base));
+    } else if (entry.isFile()) {
+      files.push(fullPath.slice(base.length + 1));
+    }
+  }
+  return files;
+}
+
+function normalizeRelPath(value) {
+  return String(value || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
+function featureScopeFromInput(input) {
+  const value = normalizeRelPath(input);
+  if (!value) return null;
+
+  const match = value.match(/^(?:\.aw_docs\/)?features\/([^/]+)$/);
+  if (!match) {
+    throw new Error('Docs-only publish path must be .aw_docs/features/<feature-slug> or use --feature <feature-slug>.');
+  }
+  return awDocsFeatureScope(match[1]);
+}
+
+function awDocsFeatureScope(featureSlug) {
+  const slug = String(featureSlug || '').trim();
+  if (!slug || slug === 'true') {
+    throw new Error('Missing feature slug. Use: aw push --aw-docs-only --feature <feature-slug>');
+  }
+  if (!/^[A-Za-z0-9._-]+$/.test(slug)) {
+    throw new Error(`Invalid feature slug "${slug}". Feature slugs may contain letters, numbers, dot, underscore, and dash only.`);
+  }
+  return {
+    type: 'feature',
+    slug,
+    relPrefix: `features/${slug}`,
+  };
+}
+
+function resolveAwDocsScope(input, featureFlag) {
+  const inputScope = featureScopeFromInput(input);
+  const flagScope = featureFlag ? awDocsFeatureScope(featureFlag) : null;
+  if (inputScope && flagScope && inputScope.relPrefix !== flagScope.relPrefix) {
+    throw new Error(`Docs-only publish received conflicting scopes: ${inputScope.relPrefix} and ${flagScope.relPrefix}.`);
+  }
+  return flagScope || inputScope;
+}
+
+function collectProjectAwDocs(cwd, home, scope = null) {
+  const projectRoot = getProjectRoot(cwd, home);
+  const source = join(projectRoot, AW_DOCS_DIR);
+
+  if (!existsSync(source)) return { projectRoot, files: [] };
+
+  const files = [];
+  if (scope) {
+    const sourceRoot = join(source, scope.relPrefix);
+    if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+      throw new Error(`No publishable AW docs found under ${AW_DOCS_DIR}/${scope.relPrefix}.`);
+    }
+    for (const relFromRoot of collectFiles(sourceRoot)) {
+      const relPath = `${scope.relPrefix}/${relFromRoot}`.replace(/\\/g, '/');
+      files.push({
+        relPath,
+        absPath: join(source, relPath),
+      });
+    }
+    return { projectRoot, files };
+  }
+
+  for (const root of PROJECT_AW_DOCS_AUTO_ROOTS) {
+    const sourceRoot = join(source, root);
+    if (!existsSync(sourceRoot)) continue;
+    for (const relFromRoot of collectFiles(sourceRoot)) {
+      const relPath = `${root}/${relFromRoot}`.replace(/\\/g, '/');
+      files.push({
+        relPath,
+        absPath: join(source, relPath),
+      });
+    }
+  }
+  return { projectRoot, files };
+}
+
+function readAwDocsConfig(projectRoot) {
+  const configPath = join(projectRoot, AW_DOCS_DIR, 'config.json');
+  if (!existsSync(configPath)) return {};
+
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    throw new Error(`Invalid ${AW_DOCS_DIR}/config.json: ${e.message}`);
+  }
+}
+
+function writeAwDocsConfigIfChanged(projectRoot, config) {
+  const configPath = join(projectRoot, AW_DOCS_DIR, 'config.json');
+  const nextText = JSON.stringify(config, null, 2) + '\n';
+  const existingText = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  if (existingText !== nextText) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, nextText);
+  }
+}
+
+function ensureAwDocsPublishConfig(projectRoot) {
+  const config = readAwDocsConfig(projectRoot);
+  const defaultGithubDocs = defaultAwDocsGithubDocsConfig();
+  const next = {
+    ...config,
+    sync: {
+      ...(config.sync || {}),
+      github_docs: {
+        ...defaultGithubDocs,
+        ...(config.sync?.github_docs || {}),
+      },
+    },
+  };
+
+  writeAwDocsConfigIfChanged(projectRoot, next);
+  return next;
+}
+
+function repoCloneUrl(repo) {
+  const value = String(repo || '').trim();
+  if (!value) return AW_DOCS_URL;
+  if (/^(?:https?:\/\/|git@|ssh:\/\/|file:\/\/)/.test(value)) return value;
+  return `https://github.com/${value.replace(/\.git$/, '')}.git`;
+}
+
+function resolveAwDocsPublishConfig(projectRoot) {
+  const config = ensureAwDocsPublishConfig(projectRoot);
+  const githubDocs = config.sync?.github_docs || {};
+  const repo = process.env.AW_DOCS_REPO || githubDocs.repo || AW_DOCS_REPO;
+  const branch = AW_DOCS_BASE_BRANCH;
+  const repoUrl = process.env.AW_DOCS_REPO_URL || githubDocs.repo_url || repoCloneUrl(repo);
+  const dest = safePathSegment(process.env.AW_DOCS_PUBLISH_DIR || githubDocs.dest || AW_DOCS_PUBLISH_DIR, AW_DOCS_PUBLISH_DIR);
+  const teamofoneBaseUrl = String(
+    process.env.AW_DOCS_TEAMOFONE_BASE_URL
+      || githubDocs.teamofone_base_url
+      || AW_DOCS_TEAMOFONE_BASE_URL,
+  ).trim();
+  const publicBaseUrl = process.env.AW_DOCS_PUBLIC_BASE_URL
+    || githubDocs.public_base_url
+    || AW_DOCS_PUBLIC_BASE_URL
+    || `https://github.com/${String(repo).replace(/\.git$/, '')}/blob/${branch}`;
+
+  return {
+    enabled: githubDocs.enabled !== false,
+    repo,
+    repoUrl,
+    branch,
+    seedBranch: process.env.AW_DOCS_SEED_BRANCH || githubDocs.seed_branch || AW_DOCS_SEED_BRANCH,
+    dest,
+    teamofoneBaseUrl: normalizeTeamOfOneBaseUrl(teamofoneBaseUrl),
+    publicBaseUrl,
+  };
+}
+
+function isOnlyUntrackedAwSymlink(status, cloneDir) {
+  const lines = status.trim().split('\n').filter(Boolean);
+  if (lines.length !== 1 || !/^\?\?\s+\.aw\/?$/.test(lines[0])) return false;
+  try {
+    return lstatSync(join(cloneDir, '.aw')).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+async function removeTrackedAwSymlink(cloneDir) {
+  try {
+    if (!lstatSync(join(cloneDir, '.aw')).isSymbolicLink()) return false;
+  } catch {
+    return false;
+  }
+
+  try {
+    await execFile('git', ['ls-files', '--error-unmatch', '.aw'], {
+      cwd: cloneDir,
+      encoding: 'utf8',
+    });
+  } catch {
+    return false;
+  }
+
+  await execFile('git', ['rm', '-f', '.aw'], {
+    cwd: cloneDir,
+    encoding: 'utf8',
+  });
+  return true;
+}
+
+async function getGitStatus(repoDir) {
+  const { stdout } = await execFile('git', ['status', '--porcelain'], {
+    cwd: repoDir,
+    encoding: 'utf8',
+  });
+  return stdout;
+}
+
+function parseGitHubRepo(remoteUrl) {
+  const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
+  if (!match) return null;
+  return `${match[1]}/${match[2].replace(/\.git$/, '')}`;
+}
+
+function repoSlugFromSource(sourceRepo, projectRoot) {
+  const repoName = sourceRepo?.split('/').pop() || basename(projectRoot);
+  return repoName
+    .replace(/\.git$/, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'project';
+}
+
+function safePathSegment(value, fallback) {
+  return String(value || fallback)
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || fallback;
+}
+
+async function getProjectSourceRepo(projectRoot) {
+  if (process.env.AW_DOCS_SOURCE_REPO) return process.env.AW_DOCS_SOURCE_REPO;
+
+  try {
+    const { stdout } = await execFile('git', ['config', '--get', 'remote.origin.url'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    });
+    const parsed = parseGitHubRepo(stdout);
+    if (parsed) return parsed;
+  } catch (e) {
+    if (process.env.AW_DEBUG) fmt.logWarn(`Could not resolve project git remote for AW docs: ${e.message}`);
+  }
+
+  return `local/${basename(projectRoot)}`;
+}
+
+async function ensureAwDocsRepoClone(home, publishConfig) {
+  const cloneDir = process.env.AW_DOCS_WORKTREE || join(home, '.aw-ghl-aw-docs');
+
+  if (!existsSync(join(cloneDir, '.git'))) {
+    await execFile('git', ['clone', publishConfig.repoUrl, cloneDir], {
+      encoding: 'utf8',
+    });
+  }
+
+  let status = await getGitStatus(cloneDir);
+  if (status.trim() && isOnlyUntrackedAwSymlink(status, cloneDir)) {
+    rmSync(join(cloneDir, '.aw'), { force: true });
+    status = await getGitStatus(cloneDir);
+  }
+  if (status.trim()) {
+    throw new Error([
+      `AW docs repo worktree is dirty: ${cloneDir}`,
+      status.trim(),
+      'Clean the cached docs repo or set AW_DOCS_WORKTREE to a clean clone before publishing.',
+    ].join('\n'));
+  }
+
+  await execFile('git', ['fetch', 'origin'], {
+    cwd: cloneDir,
+    encoding: 'utf8',
+  });
+
+  const hasPublishBranch = await remoteBranchExists(cloneDir, publishConfig.branch);
+  const checkoutStart = hasPublishBranch
+    ? `origin/${publishConfig.branch}`
+    : `origin/${publishConfig.seedBranch}`;
+
+  await execFile('git', ['checkout', '-B', publishConfig.branch, checkoutStart], {
+    cwd: cloneDir,
+    encoding: 'utf8',
+  });
+
+  if (hasPublishBranch) {
+    await execFile('git', ['pull', '--ff-only', 'origin', publishConfig.branch], {
+      cwd: cloneDir,
+      encoding: 'utf8',
+    });
+  }
+  await removeTrackedAwSymlink(cloneDir);
+  return cloneDir;
+}
+
+async function remoteBranchExists(repoDir, branchName) {
+  try {
+    await execFile('git', ['rev-parse', '--verify', `origin/${branchName}`], {
+      cwd: repoDir,
+      encoding: 'utf8',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function appendPathToUrl(baseUrl, path) {
+  const encodedPath = path.split('/').map(encodeURIComponent).join('/');
+  const hashIndex = baseUrl.indexOf('#');
+  const withoutHash = hashIndex === -1 ? baseUrl : baseUrl.slice(0, hashIndex);
+  const hash = hashIndex === -1 ? '' : baseUrl.slice(hashIndex);
+  const queryIndex = withoutHash.indexOf('?');
+  const basePath = queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
+  const query = queryIndex === -1 ? '' : withoutHash.slice(queryIndex);
+  return `${basePath.replace(/\/$/, '')}/${encodedPath}${query}${hash}`;
+}
+
+function normalizeTeamOfOneBaseUrl(baseUrl) {
+  const value = String(baseUrl || '').trim();
+  if (!value) return '';
+  if (/^https?:\/\//i.test(value)) return value;
+  if (value.startsWith('/')) return `${AW_DOCS_TEAMOFONE_ORIGIN.replace(/\/$/, '')}${value}`;
+  return `https://${value.replace(/^\/+/, '')}`;
+}
+
+function appendQueryParam(url, key, value) {
+  const hashIndex = url.indexOf('#');
+  const withoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
+  const separator = withoutHash.includes('?') ? '&' : '?';
+  return `${withoutHash}${separator}${encodeURIComponent(key)}=${encodeURIComponent(value)}${hash}`;
+}
+
+function awDocsTeamOfOneUrl(publishedPath, publishConfig) {
+  if (!publishConfig.teamofoneBaseUrl) return null;
+  return appendQueryParam(
+    appendPathToUrl(publishConfig.teamofoneBaseUrl, publishedPath),
+    'ref',
+    publishConfig.branch,
+  );
+}
+
+function awDocsPublicUrl(publishedPath, publishConfig) {
+  return appendPathToUrl(publishConfig.publicBaseUrl, publishedPath);
+}
+
+function awDocsRemoteUrl(publishedPath, publishConfig) {
+  return awDocsTeamOfOneUrl(publishedPath, publishConfig)
+    || awDocsPublicUrl(publishedPath, publishConfig);
+}
+
+function awDocsRepositoryUrl(publishedPath, publishConfig) {
+  const repo = String(publishConfig.repo || AW_DOCS_REPO).replace(/\.git$/, '');
+  if (!repo.includes('/')) return awDocsPublicUrl(publishedPath, publishConfig);
+  return appendPathToUrl(`https://github.com/${repo}/blob/${publishConfig.branch}`, publishedPath);
+}
+
+function printAwDocsLinks(links, limit = 10) {
+  fmt.logInfo(chalk.bold('Remote Docs'));
+  for (const link of links.slice(0, limit)) {
+    fmt.logInfo(`  ${chalk.dim(link.relPath)}`);
+    fmt.logInfo(`    TeamOfOne: ${chalk.cyan(link.remoteUrl)}`);
+    if (link.repositoryUrl && link.repositoryUrl !== link.remoteUrl) {
+      fmt.logInfo(`    GitHub: ${chalk.cyan(link.repositoryUrl)}`);
+    }
+  }
+  if (links.length > limit) {
+    fmt.logInfo(chalk.dim(`...and ${links.length - limit} more`));
+  }
+}
+
+function writeAwDocsLinkSummary(projectRoot, links, publishConfig) {
+  const summaryPath = join(projectRoot, AW_DOCS_DIR, 'last-publish.json');
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    branch: publishConfig.branch,
+    repo: publishConfig.repo,
+    targetPath: publishConfig.dest,
+    links,
+  };
+  try {
+    writeFileSync(summaryPath, JSON.stringify(payload, null, 2) + '\n');
+  } catch (e) {
+    if (process.env.AW_DEBUG) fmt.logWarn(`Could not write AW docs link summary: ${e.message}`);
+  }
+}
+
+async function commitAndPushAwDocsRepo(docsRepoDir, { message, branch }) {
+  await execFile('git', ['add', '-A'], { cwd: docsRepoDir, encoding: 'utf8' });
+  await execFile('git', ['commit', '-m', message], {
+    cwd: docsRepoDir,
+    encoding: 'utf8',
+  });
+  await execFile('git', ['push', '-u', 'origin', `HEAD:${branch}`], {
+    cwd: docsRepoDir,
+    encoding: 'utf8',
+  });
+}
+
+function titleForAwDoc(relPath) {
+  const name = basename(relPath);
+  const base = name.replace(/\.(md|html|json)$/i, '');
+  const label = base.charAt(0).toUpperCase() + base.slice(1);
+  const ext = name.includes('.') ? name.split('.').pop().toUpperCase() : 'DOC';
+  return `${label} ${ext}`;
+}
+
+function updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig, scope = null }) {
+  const manifestPath = join(docsRepoDir, 'manifest.json');
+  const manifest = existsSync(manifestPath)
+    ? JSON.parse(readFileSync(manifestPath, 'utf8'))
+    : { teams: {}, awDocs: { repos: {} } };
+  const now = new Date().toISOString();
+
+  manifest.updatedAt = now;
+  manifest.awDocs ||= { repos: {} };
+  manifest.awDocs.repos ||= {};
+  const repoEntry = manifest.awDocs.repos[repoSlug] || {};
+  repoEntry.slug = repoSlug;
+  repoEntry.sourceRepo = sourceRepo;
+  repoEntry.users ||= {};
+  const existingUser = repoEntry.users[githubUsername] || {};
+  const nextDocs = docs.map(doc => ({
+    relPath: doc.relPath,
+    publishedPath: doc.publishedPath,
+    remoteUrl: awDocsRemoteUrl(doc.publishedPath, publishConfig),
+    repositoryUrl: awDocsRepositoryUrl(doc.publishedPath, publishConfig),
+    sha: createHash('sha256').update(readFileSync(join(docsRepoDir, doc.publishedPath))).digest('hex'),
+    syncedAt: now,
+    title: titleForAwDoc(doc.relPath),
+  }));
+  const preservedDocs = scope?.relPrefix
+    ? (existingUser.docs || []).filter(doc => !String(doc.relPath || '').startsWith(`${scope.relPrefix}/`))
+    : [];
+
+  repoEntry.users[githubUsername] = {
+    ...existingUser,
+    githubUsername,
+    docs: scope?.relPrefix ? [...preservedDocs, ...nextDocs] : nextDocs,
+  };
+  manifest.awDocs.repos[repoSlug] = repoEntry;
+
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+async function publishProjectAwDocs(cwd, home, dryRun, scope = null) {
+  const { projectRoot, files } = collectProjectAwDocs(cwd, home, scope);
+  if (files.length === 0) return { hasDocs: false, publishedPaths: [] };
+
+  const publishConfig = resolveAwDocsPublishConfig(projectRoot);
+  if (!publishConfig.enabled) {
+    fmt.logWarn(`${AW_DOCS_DIR}/config.json sync.github_docs.enabled is false; skipping AW docs publish`);
+    return { hasDocs: true, skipped: true, publishedPaths: [], links: [] };
+  }
+
+  const sourceRepo = await getProjectSourceRepo(projectRoot);
+  const repoSlug = repoSlugFromSource(sourceRepo, projectRoot);
+  const githubUsername = safePathSegment(await getGitHubUser(), 'unknown');
+  const docs = files.map(file => ({
+    ...file,
+    publishedPath: `${publishConfig.dest}/${repoSlug}/${githubUsername}/${file.relPath}`,
+  }));
+  const publishedPaths = docs.map(doc => doc.publishedPath);
+  const links = docs.map(doc => ({
+    relPath: doc.relPath,
+    publishedPath: doc.publishedPath,
+    remoteUrl: awDocsRemoteUrl(doc.publishedPath, publishConfig),
+    repositoryUrl: awDocsRepositoryUrl(doc.publishedPath, publishConfig),
+  }));
+
+  if (dryRun) {
+    fmt.logInfo(`${chalk.bold(files.length)} AW doc${files.length > 1 ? 's' : ''} to publish directly to ${publishConfig.repo}`);
+    for (const link of links.slice(0, 40)) {
+      fmt.logMessage(`  ${chalk.yellow('AWDOC')}/${link.publishedPath}`);
+      fmt.logMessage(`    ${chalk.cyan(link.remoteUrl)}`);
+    }
+    if (links.length > 40) fmt.logMessage(`  ...and ${links.length - 40} more`);
+    fmt.logWarn('No AW docs published (--dry-run)');
+    return { hasDocs: true, publishedPaths, links };
+  }
+
+  const s = fmt.spinner();
+  s.start(`Publishing ${files.length} AW doc${files.length > 1 ? 's' : ''} to ${publishConfig.repo}...`);
+  try {
+    const docsRepoDir = await ensureAwDocsRepoClone(home, publishConfig);
+    const deleteTarget = scope?.relPrefix
+      ? join(docsRepoDir, publishConfig.dest, repoSlug, githubUsername, scope.relPrefix)
+      : join(docsRepoDir, publishConfig.dest, repoSlug, githubUsername);
+    rmSync(deleteTarget, {
+      recursive: true,
+      force: true,
+    });
+    for (const doc of docs) {
+      const dest = join(docsRepoDir, doc.publishedPath);
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(doc.absPath, dest);
+    }
+    updateAwDocsManifest(docsRepoDir, { repoSlug, sourceRepo, githubUsername, docs, publishConfig, scope });
+
+    const { stdout: status } = await execFile('git', ['status', '--porcelain'], {
+      cwd: docsRepoDir,
+      encoding: 'utf8',
+    });
+    if (!status.trim()) {
+      s.stop('AW docs already up to date');
+      writeAwDocsLinkSummary(projectRoot, links, publishConfig);
+      printAwDocsLinks(links);
+      return { hasDocs: true, publishedPaths, links };
+    }
+
+    await commitAndPushAwDocsRepo(docsRepoDir, {
+      message: scope?.relPrefix
+        ? `docs(aw): sync ${repoSlug}/${githubUsername} ${scope.relPrefix}`
+        : `docs(aw): sync ${repoSlug}/${githubUsername} AW docs`,
+      branch: publishConfig.branch,
+    });
+    writeAwDocsLinkSummary(projectRoot, links, publishConfig);
+    s.stop(`Published AW docs to ${publishConfig.repo}`);
+    printAwDocsLinks(links);
+    return { hasDocs: true, publishedPaths, links };
+  } catch (e) {
+    s.stop(chalk.red('AW docs publish failed'));
+    throw e;
+  }
+}
 
 // ── PR content generation ────────────────────────────────────────────
 
 // Auto-generate a branch name from the files being pushed.
-function generateBranchName(files) {
+function generateBranchName(files, extraPaths = []) {
   const shortId = Date.now().toString(36).slice(-5);
 
+  if (files.length === 0 && extraPaths.length > 0) {
+    return `${managedBranchPrefix(extraPaths)}-${shortId}`;
+  }
   if (files.length === 0) return `sync/state-${shortId}`;
 
   const namespaces = [...new Set(files.map(f => f.namespace))];
@@ -75,8 +704,10 @@ function parseCommitFiles(commits) {
   return result;
 }
 
-function generatePrTitle(files, awHome = null) {
+function generatePrTitle(files, awHome = null, extraPaths = []) {
   if (files.length === 0) {
+    if (extraPaths.length > 0) return managedPrTitle(extraPaths);
+
     const commits = awHome ? logAheadOfMain(awHome) : [];
     const parsed = parseCommitFiles(commits);
 
@@ -123,7 +754,7 @@ function generatePrTitle(files, awHome = null) {
 
 const AW_BRANDING = `---\n⟁ Generated by [AW CLI](https://platform.docs/agentic-workspace/guides/cli)`;
 
-function generatePrBody(files, newNamespaces, awHome = null) {
+function generatePrBody(files, newNamespaces, awHome = null, extraPaths = []) {
   const added = files.filter(f => !f.deleted);
   const deleted = files.filter(f => f.deleted);
   const bodyParts = [];
@@ -131,7 +762,10 @@ function generatePrBody(files, newNamespaces, awHome = null) {
   if (files.length === 0) {
     const commits = awHome ? logAheadOfMain(awHome) : [];
     bodyParts.push('## What\'s included', '');
-    if (commits.length > 0) {
+    if (extraPaths.length > 0) {
+      bodyParts.push(`Syncing ${managedPathSummary(extraPaths)}.`, '', '### Paths', '');
+      bodyParts.push(...formatManagedPathList(extraPaths));
+    } else if (commits.length > 0) {
       for (const c of commits) {
         bodyParts.push(`- \`${c.hash}\` ${c.message}`);
       }
@@ -180,11 +814,16 @@ function generatePrBody(files, newNamespaces, awHome = null) {
     bodyParts.push('', `> **New namespace${newNamespaces.length > 1 ? 's' : ''}:** \`${newNamespaces.join('`, `')}\` — CODEOWNERS entr${newNamespaces.length > 1 ? 'ies' : 'y'} auto-added.`);
   }
 
+  if (extraPaths.length > 0) {
+    bodyParts.push('', '### Managed Docs', '', `Also syncing ${managedPathSummary(extraPaths)}.`, '');
+    bodyParts.push(...formatManagedPathList(extraPaths));
+  }
+
   bodyParts.push('', AW_BRANDING);
   return bodyParts.join('\n');
 }
 
-function generateCommitMsg(files) {
+function generateCommitMsg(files, extraPaths = []) {
   const added = files.filter(f => !f.deleted);
   const deleted = files.filter(f => f.deleted);
   const addedParts = Object.entries(groupBy(added, 'type')).map(([t, items]) => `${items.length} ${singular(t, items.length)}`);
@@ -194,10 +833,16 @@ function generateCommitMsg(files) {
   const version = VERSION;
   const trailer = `\n\nGenerated-By: aw/${version}\n${AW_CO_AUTHOR}`;
 
+  if (files.length === 0 && extraPaths.length > 0) {
+    return `docs: sync ${managedPathSummary(extraPaths)}${trailer}`;
+  }
   if (files.length === 1) {
     const f = files[0];
     return `registry: ${f.deleted ? 'remove' : 'add'} ${f.type}/${f.slug} ${f.deleted ? 'from' : 'to'} ${f.namespace}${trailer}`;
   }
+  if (extraPaths.length > 0) {
+    return `registry: sync ${files.length} files and ${managedPathSummary(extraPaths)}${trailer}`;
+  }
   return `registry: sync ${files.length} files (${countParts.join(', ')})${trailer}`;
 }
 
@@ -368,15 +1013,22 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
 
   // ── Dry-run: just list files and exit ──────────────────────────────
   if (dryRun) {
-    if (files.length === 0) {
+    if (files.length === 0 && extraPaths.length === 0) {
       fmt.logInfo('No new changes — would branch current state');
     } else {
-      fmt.logInfo(`${chalk.bold(files.length)} file${files.length > 1 ? 's' : ''} to push (${countParts.join(', ')})`);
+      const total = files.length + extraPaths.length;
+      const registrySummary = countParts.length > 0 ? countParts.join(', ') : null;
+      const extraSummary = extraPaths.length > 0 ? managedPathSummary(extraPaths) : null;
+      const summary = [registrySummary, extraSummary].filter(Boolean).join(', ');
+      fmt.logInfo(`${chalk.bold(total)} file${total > 1 ? 's' : ''} to push (${summary})`);
       for (const f of files) {
         const ns = chalk.dim(` [${f.namespace}]`);
         const label = f.deleted ? chalk.red('DELETE') : chalk.yellow(f.type);
         fmt.logMessage(`  ${label}/${f.slug}${ns}`);
       }
+      for (const p of extraPaths) {
+        fmt.logMessage(`  ${chalk.yellow('DOC')}/${p}`);
+      }
     }
     fmt.logWarn('No changes made (--dry-run)');
     fmt.outro(chalk.dim('Remove --dry-run to push'));
@@ -385,7 +1037,7 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
 
   // ── Phase 1: Prepare commit ────────────────────────────────────────
   const prepLabel = files.length === 0
-    ? 'Creating upload branch from HEAD...'
+    ? (extraPaths.length > 0 ? `Preparing ${managedPathSummary(extraPaths)}...` : 'Creating upload branch from HEAD...')
     : `Preparing ${countParts.join(', ')}...`;
 
   const s = fmt.spinner();
@@ -408,14 +1060,14 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
   if (newNamespaces.length > 0 && existsSync(codeownersPath)) {
     pathsToStage.push('CODEOWNERS');
   }
-  // Also stage any extra paths (content/, CODEOWNERS manual edits) passed from the caller
+  // Also stage any extra platform-doc paths (content/, CODEOWNERS manual edits) passed from the caller.
   for (const p of extraPaths) {
     if (!pathsToStage.includes(p)) pathsToStage.push(p);
   }
 
-  const commitMsg = generateCommitMsg(files);
-  const prTitle = generatePrTitle(files, awHome);
-  const prBody = generatePrBody(files, newNamespaces, awHome);
+  const commitMsg = generateCommitMsg(files, extraPaths);
+  const prTitle = generatePrTitle(files, awHome, extraPaths);
+  const prBody = generatePrBody(files, newNamespaces, awHome, extraPaths);
 
   // ── Phase 2: Commit + push branch ──────────────────────────────────
   s.message('Creating branch and pushing...');
@@ -423,7 +1075,7 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
   let finalBranch;
   try {
     if (worktreeFlow) {
-      finalBranch = await createPushBranch(awHome, generateBranchName(files), pathsToStage, commitMsg, preStaged);
+      finalBranch = await createPushBranch(awHome, generateBranchName(files, extraPaths), pathsToStage, commitMsg, preStaged);
     } else {
       // Only return to main if there are no unmerged commits ahead.
       // If we're already on a push branch (previous PR not merged), create the
@@ -435,11 +1087,11 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
           return;
         }
       }
-      finalBranch = await createPushBranch(awHome, generateBranchName(files), pathsToStage, commitMsg, preStaged);
+      finalBranch = await createPushBranch(awHome, generateBranchName(files, extraPaths), pathsToStage, commitMsg, preStaged);
       // Stay on the push branch — returning to main makes it look like changes disappeared in IDE
     }
     const branchLabel = files.length === 0
-      ? 'Branch created'
+      ? (extraPaths.length > 0 ? `Pushed ${managedPathSummary(extraPaths)}` : 'Branch created')
       : `Pushed ${countParts.join(', ')}`;
     s.stop(branchLabel);
   } catch (e) {
@@ -468,6 +1120,7 @@ async function doPush(files, awHome, dryRun, worktreeFlow = false, preStaged = f
 export async function pushCommand(args) {
   const input = args._positional?.[0];
   const dryRun = args['--dry-run'] === true;
+  const docsOnly = args['--aw-docs-only'] === true || args['--docs-only'] === true;
   const cwd = process.cwd();
 
   const HOME = homedir();
@@ -490,6 +1143,25 @@ export async function pushCommand(args) {
     return;
   }
 
+  if (docsOnly) {
+    try {
+      const scope = resolveAwDocsScope(input, args['--feature']);
+      const result = await publishProjectAwDocs(cwd, HOME, dryRun, scope);
+      if (!result.hasDocs) {
+        fmt.cancel(scope
+          ? `No publishable AW docs found under ${AW_DOCS_DIR}/${scope.relPrefix}.`
+          : 'No publishable AW docs found under .aw_docs/features or .aw_docs/html.');
+        return;
+      }
+      if (dryRun) fmt.outro(chalk.dim('Remove --dry-run to publish AW docs'));
+      else fmt.outro('⟁  AW docs publish complete');
+      return;
+    } catch (e) {
+      fmt.cancel(`AW docs publish failed: ${e.message}`);
+      return;
+    }
+  }
+
   const repoUrl = REGISTRY_URL;
   if (!isValidClone(awHome, repoUrl)) {
     if (!input && hasRulesChanges(cwd)) {
@@ -505,23 +1177,18 @@ export async function pushCommand(args) {
   if (!input) {
     const rulesChanged = hasRulesChanges(cwd);
 
-    // Extra paths outside .aw_registry/ that aw also manages: content/ and CODEOWNERS.
+    // Extra paths outside .aw_registry/ that aw also manages through the platform-docs PR flow: content/ and CODEOWNERS.
     // Detect staged variants for staged-mode and unstaged variants for auto-mode.
     const getExtraStagedPaths = async () => {
       try {
-        const { stdout } = await exec(`git -C "${awHome}" diff --cached --name-only -- content/ CODEOWNERS`);
-        return stdout.trim().split('\n').filter(Boolean);
+        const { stdout } = await exec(`git -C "${awHome}" diff --cached --name-only -- ${EXTRA_PUSH_PATHS_ARG}`);
+        return [...new Set(stdout.trim().split('\n').filter(Boolean))];
       } catch { return []; }
     };
     const getExtraChangedPaths = async () => {
       try {
-        const { stdout } = await exec(`git -C "${awHome}" status --porcelain -- content/ CODEOWNERS`);
-        // git status --porcelain prefix is XY (2 chars) + optional space + path.
-        // Staged-only files: `M path` (2-char prefix); unstaged files: ` M path` (3-char prefix).
-        // slice(2).trimStart() handles both cases correctly.
-        return stdout.trim().split('\n').filter(Boolean)
-          .map(l => l.slice(2).trimStart())
-          .filter(Boolean);
+        const { stdout } = await exec(`git -C "${awHome}" status --porcelain --ignored=matching -uall -- ${EXTRA_PUSH_PATHS_ARG}`);
+        return parseExtraStatusPaths(stdout);
       } catch { return []; }
     };
 
@@ -551,7 +1218,15 @@ export async function pushCommand(args) {
       return;
     }
 
-    // ── Auto mode: stage all changes in .aw_registry/ ─────────────────
+    // ── Auto mode: publish generated project .aw_docs/ directly, then handle registry/platform docs ─
+    let awDocsPublish;
+    try {
+      awDocsPublish = await publishProjectAwDocs(cwd, HOME, dryRun);
+    } catch (e) {
+      fmt.cancel(`AW docs publish failed: ${e.message}`);
+      return;
+    }
+
     const changes = detectChanges(awHome, REGISTRY_DIR);
     const extraChanged = await getExtraChangedPaths();
     const allEntries = [
@@ -560,6 +1235,17 @@ export async function pushCommand(args) {
       ...changes.deleted.map(e => ({ ...e, deleted: true })),
     ];
 
+    if (allEntries.length === 0 && extraChanged.length === 0 && awDocsPublish?.hasDocs) {
+      if (rulesChanged) {
+        fmt.logInfo('Detected changes under platform rules — redirecting to `aw push-rules`.');
+        pushRulesCommand(args);
+        return;
+      }
+      if (dryRun) fmt.outro(chalk.dim('Remove --dry-run to publish'));
+      else fmt.outro('⟁  Push complete');
+      return;
+    }
+
     if (allEntries.length === 0 && extraChanged.length === 0 && commitsAheadOfMain(awHome) > 0) {
       fmt.logInfo(`${chalk.dim('mode:')} auto (no new changes — branching current state)`);
       await doPush([], awHome, dryRun, worktreeFlow, false);

package/constants.mjs

@@ -22,6 +22,29 @@ export const REGISTRY_DIR = '.aw_registry';
 /** Directory in platform-docs repo containing documentation (pulled into platform/docs/) */
 export const DOCS_SOURCE_DIR = 'content';
 
+/** Project-local directory containing generated AW planning/spec artifacts */
+export const AW_DOCS_DIR = '.aw_docs';
+
+/** Generated AW docs aggregation repository */
+export const AW_DOCS_REPO = process.env.AW_DOCS_REPO || 'GoHighLevel/ghl-aw-docs';
+export const AW_DOCS_URL = process.env.AW_DOCS_REPO_URL || `https://github.com/${AW_DOCS_REPO}.git`;
+/** Canonical branch for all generated AW docs publishes. Intentionally not configurable per run. */
+export const AW_DOCS_BASE_BRANCH = 'master-sync';
+export const AW_DOCS_SEED_BRANCH = process.env.AW_DOCS_SEED_BRANCH || 'scaffold';
+export const AW_DOCS_PUBLISH_DIR = 'aw_docs';
+export const AW_DOCS_PUBLIC_BASE_URL = process.env.AW_DOCS_PUBLIC_BASE_URL || `https://github.com/${AW_DOCS_REPO}/blob/${AW_DOCS_BASE_BRANCH}`;
+export const AW_DOCS_TEAMOFONE_ORIGIN = process.env.AW_DOCS_TEAMOFONE_ORIGIN || 'https://teamofone.msgsndr.net';
+export const AW_DOCS_TEAMOFONE_BASE_URL = process.env.AW_DOCS_TEAMOFONE_BASE_URL || `${AW_DOCS_TEAMOFONE_ORIGIN}/too/docs/GoHighLevel/ghl-aw-docs`;
+
+export function defaultAwDocsGithubDocsConfig() {
+  return {
+    enabled: true,
+    repo: AW_DOCS_REPO,
+    dest: AW_DOCS_PUBLISH_DIR,
+    teamofone_base_url: AW_DOCS_TEAMOFONE_BASE_URL,
+  };
+}
+
 /** Persistent git clone root — ~/.aw/ */
 export const AW_HOME = join(homedir(), '.aw');
 

package/git.mjs

@@ -5,7 +5,7 @@ import { mkdtempSync, existsSync, lstatSync, rmSync, readFileSync, symlinkSync,
 import { join, basename, dirname } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { promisify } from 'node:util';
-import { REGISTRY_BASE_BRANCH, REGISTRY_DIR, DOCS_SOURCE_DIR, RULES_SOURCE_DIR } from './constants.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_DIR, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR } from './constants.mjs';
 
 const exec = promisify(execCb);
 
@@ -145,7 +145,8 @@ export function cleanup(tempDir) {
  * e.g., ["platform", "dev/agents/debugger"] -> [".aw_registry/platform", ".aw_registry/dev/agents/debugger"]
  *
  * When "platform" is in the paths, also includes the repo's docs source
- * directory (content/) so docs are pulled on-the-fly into platform/docs/.
+ * directory (content/) and generated AW docs (.aw_docs/) so docs are pulled
+ * on-the-fly into platform/docs/ and the local AW docs cache.
  */
 export function includeToSparsePaths(paths) {
   const result = new Set();
@@ -155,6 +156,7 @@ export function includeToSparsePaths(paths) {
   result.add(`${REGISTRY_DIR}/AW-PROTOCOL.md`);
   if (paths.includes('platform')) {
     result.add(DOCS_SOURCE_DIR);
+    result.add(AW_DOCS_DIR);
     result.add(RULES_SOURCE_DIR);
   }
   return [...result];
@@ -497,7 +499,7 @@ export function commitToCurrentBranch(awHome, files, commitMsg, preStaged = fals
   if (!preStaged) {
     try {
       const quotedFiles = files.map(f => `"${f}"`).join(' ');
-      execSync(`git -C "${awHome}" add ${quotedFiles}`, { stdio: 'pipe' });
+      execSync(`git -C "${awHome}" add --sparse -f ${quotedFiles}`, { stdio: 'pipe' });
     } catch (e) {
       throw new Error(`Failed to stage files: ${e.message}`);
     }
@@ -553,7 +555,7 @@ export async function createPushBranch(awHome, branchName, files, commitMsg, pre
     if (!preStaged) {
       try {
         const quotedFiles = files.map(f => `"${f}"`).join(' ');
-        await exec(`git -C "${awHome}" add ${quotedFiles}`);
+        await exec(`git -C "${awHome}" add --sparse -f ${quotedFiles}`);
       } catch (e) {
         throw new Error(`Failed to stage files: ${e.message}`);
       }

package/package.json

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