@ghl-ai/aw 0.1.68 → 0.1.70-beta.0

package/aw-docs-validate.mjs

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { AW_DOCS_DIR } from './constants.mjs';
+
+export const PLAN_ARTIFACTS = [
+  { kind: 'prd', source: 'prd.md', html: 'prd.html' },
+  { kind: 'design', source: 'design.md', html: 'design.html' },
+  { kind: 'spec', source: 'spec.md', html: 'spec.html' },
+  { kind: 'tasks', source: 'tasks.md', html: 'tasks.html' },
+];
+
+const GENERATED_STATUSES = new Set(['generated', 'published', 'html_generated_and_published']);
+const SKIPPED_STATUSES = new Set(['skipped']);
+
+export function findAwDocsProjectRoot(cwd = process.cwd()) {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync(join(current, AW_DOCS_DIR))) return current;
+    const next = dirname(current);
+    if (next === current) return resolve(cwd);
+    current = next;
+  }
+}
+
+export function normalizeFeatureSlug(value) {
+  const raw = String(value || '').trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  if (!raw || raw === 'true') return '';
+  const match = raw.match(/^(?:\.aw_docs\/)?features\/([^/]+)$/);
+  const slug = match ? match[1] : raw;
+  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 slug;
+}
+
+export function resolveDocsOutputMode(projectRoot, env = process.env) {
+  const configPath = join(projectRoot, AW_DOCS_DIR, 'config.json');
+  const envMode = env.AW_DOCS_OUTPUT_MODE;
+  let configMode = '';
+
+  if (existsSync(configPath)) {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    configMode = config.docs?.outputMode || '';
+  }
+
+  return normalizeOutputMode(envMode || configMode || 'dual');
+}
+
+function normalizeOutputMode(value) {
+  const mode = String(value || 'dual').trim().toLowerCase();
+  if (mode === 'md' || mode === 'markdown-only') return 'markdown';
+  if (mode === 'html-only') return 'html';
+  if (mode === 'markdown' || mode === 'html' || mode === 'dual') return mode;
+  return 'dual';
+}
+
+export function readFeatureState(featureDir) {
+  const statePath = join(featureDir, 'state.json');
+  if (!existsSync(statePath)) return { statePath, state: null };
+  return { statePath, state: JSON.parse(readFileSync(statePath, 'utf8')) };
+}
+
+export function listExpectedPlanArtifacts(featureDir, { full = false } = {}) {
+  return PLAN_ARTIFACTS.filter(artifact => full || existsSync(join(featureDir, artifact.source)));
+}
+
+export function validateFeatureDocs(options) {
+  const projectRoot = resolve(options.projectRoot || findAwDocsProjectRoot(options.cwd));
+  const featureSlug = normalizeFeatureSlug(options.featureSlug);
+  if (!featureSlug) throw new Error('Missing feature slug. Use: aw docs validate --feature <feature-slug>');
+
+  const featureDir = join(projectRoot, AW_DOCS_DIR, 'features', featureSlug);
+  const result = {
+    ok: true,
+    projectRoot,
+    featureSlug,
+    featureDir,
+    outputMode: normalizeOutputMode(options.outputMode || resolveDocsOutputMode(projectRoot, options.env)),
+    checked: [],
+    errors: [],
+    warnings: [],
+  };
+
+  if (!existsSync(featureDir) || !statSync(featureDir).isDirectory()) {
+    addError(result, `Missing feature folder: ${AW_DOCS_DIR}/features/${featureSlug}`);
+    return result;
+  }
+
+  const { statePath, state } = readFeatureState(featureDir);
+  if (!state) {
+    addError(result, `Missing state file: ${relativeFeaturePath(projectRoot, statePath)}`);
+  }
+
+  const expected = listExpectedPlanArtifacts(featureDir, { full: options.full });
+  if (expected.length === 0) {
+    addError(result, options.full
+      ? 'Full plan validation requires prd.md, design.md, spec.md, and tasks.md.'
+      : 'No canonical planning Markdown found to validate.');
+  }
+
+  const markdownOnly = result.outputMode === 'markdown';
+  for (const artifact of expected) {
+    validateArtifact(result, artifact, { projectRoot, featureSlug, featureDir, state, markdownOnly, publishRequired: options.publishRequired });
+  }
+
+  if (state && expected.length > 0 && marksReadyForBuild(state) && result.errors.length > 0) {
+    result.warnings.push('state.json marks this feature ready for build while the HTML companion gate is failing.');
+  }
+
+  return result;
+}
+
+function validateArtifact(result, artifact, context) {
+  const sourcePath = join(context.featureDir, artifact.source);
+  const htmlPath = join(context.featureDir, artifact.html);
+  const sourceRel = featureRel(context.featureSlug, artifact.source);
+  const htmlRel = featureRel(context.featureSlug, artifact.html);
+  const entry = findCompanionEntry(context.state?.html_companion_artifacts, { sourceRel, htmlRel, kind: artifact.kind });
+
+  const record = {
+    kind: artifact.kind,
+    source: sourceRel,
+    html: htmlRel,
+    state: entry || null,
+  };
+  result.checked.push(record);
+
+  if (!existsSync(sourcePath)) {
+    addError(result, `Missing planning Markdown: ${sourceRel}`);
+    return;
+  }
+
+  if (context.markdownOnly || isExplicitMarkdownSkip(entry)) {
+    if (!context.markdownOnly && !isExplicitMarkdownSkip(entry)) {
+      addError(result, `Invalid Markdown-only skip for ${artifact.html}: missing skip_reason explicit_markdown_only.`);
+    }
+    return;
+  }
+
+  if (!existsSync(htmlPath)) {
+    addError(result, `Missing HTML companion for ${artifact.source}: ${htmlRel}`);
+  }
+
+  if (!entry) {
+    addError(result, `Missing state.json html_companion_artifacts entry for ${artifact.html}`);
+    return;
+  }
+
+  if (!GENERATED_STATUSES.has(String(entry.status || '').toLowerCase())) {
+    addError(result, `Invalid companion status for ${artifact.html}: expected generated, got ${entry.status || 'missing'}`);
+  }
+
+  if (!entry.owner || !entry.execution_mode || !entry.runner) {
+    addError(result, `Incomplete companion provenance for ${artifact.html}: owner, execution_mode, and runner are required`);
+  }
+
+  if (context.publishRequired && !hasPublishedOrBlockedLink(entry)) {
+    addError(result, `Missing publish result for ${artifact.html}: expected published links or a concrete publish blocker`);
+  }
+}
+
+function findCompanionEntry(companions, expected) {
+  if (!companions) return null;
+  const values = Array.isArray(companions)
+    ? companions
+    : Object.entries(companions).map(([key, value]) => ({ key, value }));
+
+  for (const item of values) {
+    const entry = item?.value && typeof item.value === 'object' ? item.value : item;
+    const key = item?.key || '';
+    if (!entry || typeof entry !== 'object') continue;
+    if (key === expected.htmlRel || key === basename(expected.htmlRel)) return entry;
+    if (pathMatches(entry.html_path || entry.primary || entry.publish_copy, expected.htmlRel)) return entry;
+    if (pathMatches(entry.source_path, expected.sourceRel)) return entry;
+    if (entry.artifact_kind === expected.kind || entry.kind === expected.kind) return entry;
+  }
+
+  return null;
+}
+
+function isExplicitMarkdownSkip(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const status = String(entry.status || '').toLowerCase();
+  return SKIPPED_STATUSES.has(status) && entry.skip_reason === 'explicit_markdown_only';
+}
+
+function hasPublishedOrBlockedLink(entry) {
+  const publishStatus = String(entry.publish_status || '').toLowerCase();
+  const links = entry.remote_links || {};
+  return publishStatus === 'published'
+    || Boolean(entry.remote_url || entry.teamofone_url || entry.devtools_url || links.devtools || links.teamofone)
+    || (publishStatus === 'blocked' && Boolean(entry.publish_blocker || entry.blocked_reason));
+}
+
+function marksReadyForBuild(state) {
+  const values = [state.status, state.stage_status, state.planning_status, state.next_stage].map(value => String(value || '').toLowerCase());
+  return values.some(value => value.includes('ready_for_build') || value === 'build');
+}
+
+function pathMatches(value, expectedRel) {
+  if (!value) return false;
+  const normalized = String(value).replace(/\\/g, '/').replace(/^\.\//, '');
+  const expected = expectedRel.replace(/\\/g, '/').replace(/^\.\//, '');
+  return normalized === expected || normalized.endsWith(`/${expected}`);
+}
+
+function featureRel(featureSlug, filename) {
+  return `${AW_DOCS_DIR}/features/${featureSlug}/${filename}`;
+}
+
+function relativeFeaturePath(projectRoot, absPath) {
+  if (!isAbsolute(absPath)) return absPath;
+  return absPath.startsWith(projectRoot) ? absPath.slice(projectRoot.length + 1) : absPath;
+}
+
+function addError(result, message) {
+  result.ok = false;
+  result.errors.push(message);
+}

package/c4/diagnostics.mjs

@@ -9,7 +9,7 @@
  *
  *   diagnoseAwRouterView({ awHome })
  *     Codex-relevant: replays the upstream `find * /skills/* /SKILL.md`
- *     enumeration logic against ~/.aw/.aw_registry/platform/core/skills/
+ *     enumeration logic against ~/.aw/.aw_registry/aw/skills/
  *     and reports which expected stage skills are visible to the
  *     SessionStart hook. Catches Bug A failures (registry path empty
  *     post-init).
@@ -22,7 +22,7 @@
  *     Tests both that the wrapper is registered AND that it actually
  *     emits the router (catches "wrapper installed but does nothing").
  *
- *   diagnoseSkillResolution({ harness, home, awHome, eccHome, skills })
+ *   diagnoseSkillResolution({ harness, home, awHome, skills })
  *     Multi-path × multi-skill probe. For each skill, checks four
  *     candidate paths in priority order. Top-level ok=true ONLY if
  *     using-aw-skills AND every stage skill the slim card promises
@@ -146,8 +146,8 @@ function slashShimSummaryToken(action) {
  * ───────────────────────────────────────────────────────────────────────── */
 
 /**
- * Replay of the upstream session-start.sh enumerator scan:
- *   find <awHome>/.aw_registry/platform -path STAR/skills/STAR/SKILL.md
+ * Replay of the AW registry skill scan:
+ *   find <awHome>/.aw_registry/aw/skills/<skill>/SKILL.md
  *
  * @param {object} opts
  * @param {string} opts.awHome
@@ -156,8 +156,8 @@ function slashShimSummaryToken(action) {
 export function diagnoseAwRouterView({ awHome } = {}) {
   if (!awHome) throw new Error('diagnoseAwRouterView: awHome is required');
 
-  const platformRoot = join(awHome, '.aw_registry/platform');
-  const enumerableSkills = enumerateRegistrySkills(platformRoot);
+  const awSkillsRoot = join(awHome, '.aw_registry/aw/skills');
+  const enumerableSkills = enumerateAwSkills(awSkillsRoot);
   const expected = [...EXPECTED_STAGE_SKILLS];
   const missing = expected.filter((s) => !enumerableSkills.includes(s));
   const ok = missing.length === 0;
@@ -166,38 +166,23 @@ export function diagnoseAwRouterView({ awHome } = {}) {
 }
 
 /**
- * Walk <root>/<team>/skills/<skill>/SKILL.md two levels deep, mirroring the
- * upstream find pattern. Returns the deduped sorted list of skill
- * directory names.
+ * Walk <root>/<skill>/SKILL.md and return the deduped sorted skill names.
  */
-function enumerateRegistrySkills(platformRoot) {
-  if (!existsSync(platformRoot)) return [];
+function enumerateAwSkills(awSkillsRoot) {
+  if (!existsSync(awSkillsRoot)) return [];
   const set = new Set();
-  let teams;
+  let skills;
   try {
-    teams = readdirSync(platformRoot, { withFileTypes: true });
+    skills = readdirSync(awSkillsRoot, { withFileTypes: true });
   } catch {
-    // readdir on the platform root failed (EACCES, ENOENT). Treat as
+    // readdir on the AW skills root failed (EACCES, ENOENT). Treat as
     // "no skills enumerable" — the caller's missing-list will surface it.
     return [];
   }
-  for (const team of teams) {
-    if (!team.isDirectory()) continue;
-    const skillsDir = join(platformRoot, team.name, 'skills');
-    if (!existsSync(skillsDir)) continue;
-    let skills;
-    try {
-      skills = readdirSync(skillsDir, { withFileTypes: true });
-    } catch {
-      // readdir on a team's skills/ subdirectory failed — skip this team
-      // dir but continue probing siblings.
-      continue;
-    }
-    for (const skill of skills) {
-      if (!skill.isDirectory()) continue;
-      const skillMd = join(skillsDir, skill.name, 'SKILL.md');
-      if (existsSync(skillMd)) set.add(skill.name);
-    }
+  for (const skill of skills) {
+    if (!skill.isDirectory()) continue;
+    const skillMd = join(awSkillsRoot, skill.name, 'SKILL.md');
+    if (existsSync(skillMd)) set.add(skill.name);
   }
   return [...set].sort();
 }
@@ -337,7 +322,6 @@ function envelopeContainsRouter(output) {
  * @param {Harness} opts.harness
  * @param {string}  opts.home
  * @param {string}  opts.awHome
- * @param {string}  opts.eccHome
  * @param {string[]} [opts.skills]  Default: DEFAULT_SKILL_LIST
  * @returns {{
  *   perSkill: SkillResolutionResult[],
@@ -350,12 +334,11 @@ export function diagnoseSkillResolution(opts = {}) {
   if (!opts.harness) throw new Error('diagnoseSkillResolution: harness is required');
   if (!opts.home) throw new Error('diagnoseSkillResolution: home is required');
   if (!opts.awHome) throw new Error('diagnoseSkillResolution: awHome is required');
-  if (!opts.eccHome) throw new Error('diagnoseSkillResolution: eccHome is required');
 
-  const { harness, home, awHome, eccHome } = opts;
+  const { harness, home, awHome } = opts;
   const skills = opts.skills ?? [...DEFAULT_SKILL_LIST];
 
-  const perSkill = skills.map((skill) => probeOneSkill(skill, harness, home, awHome, eccHome));
+  const perSkill = skills.map((skill) => probeOneSkill(skill, harness, home, awHome));
   const routerSkill = perSkill.find((e) => e.skill === ROUTER_SKILL) ?? {
     skill: ROUTER_SKILL,
     candidatePathsChecked: [],
@@ -374,11 +357,11 @@ function harnessSkillsDir(harness, home) {
   if (harness === 'claude-web') return join(home, '.claude/skills');
   if (harness === 'cursor-cloud') return join(home, '.cursor/skills');
   // codex-web: registry path is the canonical source; the per-harness skills
-  // dir is conventionally absent. We still probe the registry + ECC paths.
+  // dir is conventionally absent. We still probe the AW registry path.
   return null;
 }
 
-function probeOneSkill(skill, harness, home, awHome, eccHome) {
+function probeOneSkill(skill, harness, home, awHome) {
   const harnessDir = harnessSkillsDir(harness, home);
   const candidatePathsChecked = [];
 
@@ -386,8 +369,7 @@ function probeOneSkill(skill, harness, home, awHome, eccHome) {
     candidatePathsChecked.push(join(harnessDir, skill, 'SKILL.md'));
     candidatePathsChecked.push(join(harnessDir, `platform-core-${skill}`, 'SKILL.md'));
   }
-  candidatePathsChecked.push(join(awHome, '.aw_registry/platform/core/skills', skill, 'SKILL.md'));
-  candidatePathsChecked.push(join(eccHome, 'skills', skill, 'SKILL.md'));
+  candidatePathsChecked.push(join(awHome, '.aw_registry/aw/skills', skill, 'SKILL.md'));
 
   let found = null;
   for (const p of candidatePathsChecked) {
@@ -544,7 +526,7 @@ function enumerateConfigKeysOnly(filePath) {
 }
 
 function sampleRegistrySkillPaths(awHome, max) {
-  const root = join(awHome, '.aw_registry/platform');
+  const root = join(awHome, '.aw_registry/aw');
   if (!existsSync(root)) return ['  <registry not provisioned>'];
   const out = [];
   walkSkillMd(root, out, max);
@@ -569,8 +551,7 @@ function walkSkillMd(dir, out, max) {
     } else if (e.isDirectory()) {
       walkSkillMd(p, out, max);
     } else if (e.isSymbolicLink()) {
-      // Cheap stat check — symlinks pointing at SKILL.md (the bridge case)
-      // should still appear in the dump.
+      // Cheap stat check — symlinks pointing at SKILL.md should still appear.
       try {
         const st = statSync(p);
         if (st.isFile() && e.name === 'SKILL.md') out.push(p);

package/c4/index.mjs

@@ -29,7 +29,6 @@ export {
   verifyAuth,
   preflightPlatformDocs,
 } from './gitAuth.mjs';
-export { applyEccRegistryBridge } from './eccRegistryBridge.mjs';
 export {
   SLIM_CARD_HARD_CEILING_BYTES,
   REQUIRED_ENFORCEMENT_PHRASES,

package/c4/preflight.mjs

@@ -2,7 +2,7 @@
  * c4/preflight.mjs — preflight aggregator for `aw c4`.
  *
  * Composes harness, token resolution, REST-API auth verification, gh CLI
- * presence, ECC bridge-status probe, and disk-free reporting into a single
+ * presence, AW registry-skill probe, and disk-free reporting into a single
  * PreflightResult shape with per-failure recommendation strings. Pure
  * orchestration over already-tested c4 primitives — no new I/O patterns.
  *
@@ -71,10 +71,10 @@ const REC = Object.freeze({
     `Insufficient disk: ${mb}MB free (aw c4 needs at least ${DISK_FREE_THRESHOLD_MB}MB ` +
     'for ECC clone + registry pull).',
   bridgeWillInstall:
-    'ECC registry bridge will be installed during this run (Codex only — ' +
-    'Bug A workaround that symlinks ECC stage skills into ~/.aw/.aw_registry).',
+    'AW registry skills will be installed during this run from platform-docs ' +
+    '(Codex uses ~/.aw/.aw_registry/aw/skills for stage routing).',
   bridgeFailed:
-    'ECC and/or AW registry not yet provisioned — aw init will create them ' +
+    'AW registry skills are not yet provisioned — aw init will create them ' +
     'on the first c4 run; re-run preflight afterwards.',
 });
 
@@ -120,22 +120,18 @@ function classifyAuthError(verifyResult) {
   return 'unknown';
 }
 
-function probeBridgeStatus(harness, awHome, eccHome) {
+function probeBridgeStatus(harness, awHome) {
   if (harness !== 'codex-web') return 'ok';
 
-  // Bridge installs ~/.aw/.aw_registry/platform/core/skills/<aw-*>/SKILL.md
-  // symlinks pointing at ~/.aw-ecc/skills/<aw-*>/SKILL.md. If aw-plan is
-  // already present in the registry path, the bridge is a no-op (ok).
-  const bridgedSkillPath = join(
+  // AW skills are now owned by platform-docs under the top-level aw namespace.
+  // If aw-plan is already present in the registry path, routing is ready.
+  const awSkillPath = join(
     awHome,
-    '.aw_registry/platform/core/skills/aw-plan/SKILL.md',
+    '.aw_registry/aw/skills/aw-plan/SKILL.md',
   );
-  if (existsSync(bridgedSkillPath)) return 'ok';
+  if (existsSync(awSkillPath)) return 'ok';
 
-  // Bridge can install when both ECC home and the registry skeleton exist.
-  // (The aw-plan skill source must exist somewhere — the bridge follows
-  // applyEccRegistryBridge's contract; preflight only certifies feasibility.)
-  if (existsSync(eccHome) && existsSync(awHome)) return 'will-install';
+  if (existsSync(awHome)) return 'will-install';
 
   return 'failed';
 }
@@ -180,7 +176,6 @@ function buildRecommendations({
  * @param {typeof globalThis.fetch} [opts.fetchImpl]
  * @param {string}  [opts.home]      Defaults to env.HOME.
  * @param {string}  [opts.awHome]    Defaults to <home>/.aw.
- * @param {string}  [opts.eccHome]   Defaults to <home>/.aw-ecc.
  * @param {number}  [opts.diskFreeMb]  Inject for tests; production defaults to a real statfs probe.
  * @returns {Promise<PreflightResult>}
  */
@@ -200,7 +195,6 @@ export async function runPreflight(opts = {}) {
   // when env is the injected `{}`, opts.home should have been passed instead.
   const home = opts.home ?? env.HOME ?? '~';
   const awHome = opts.awHome ?? join(home, '.aw');
-  const eccHome = opts.eccHome ?? join(home, '.aw-ecc');
 
   // 1. Token resolution.
   const { token, source: tokenSource } = getGithubToken(env);
@@ -221,7 +215,7 @@ export async function runPreflight(opts = {}) {
   const ghCliPresent = runShell(shell, 'command -v gh').ok;
 
   // 4. Bridge status (codex-web only; other harnesses always 'ok').
-  const bridgeStatus = probeBridgeStatus(harness, awHome, eccHome);
+  const bridgeStatus = probeBridgeStatus(harness, awHome);
 
   // 5. Disk free MB. For tests, callers inject the value directly; in
   //    production the orchestrator passes a measured number. Defaulting to

package/cli.mjs

@@ -19,6 +19,7 @@ const COMMANDS = {
   drop:    () => import('./commands/drop.mjs').then(m => m.dropCommand),
   status:  () => import('./commands/status.mjs').then(m => m.statusCommand),
   doctor:  () => import('./commands/doctor.mjs').then(m => m.doctorCommand),
+  docs:    () => import('./commands/docs.mjs').then(m => m.docsCommand),
   routing: () => import('./commands/startup.mjs').then(m => m.routingCommand),
   startup: () => import('./commands/startup.mjs').then(m => m.startupCommand),
   mcp:     () => import('./commands/mcp.mjs').then(m => m.mcpCommand),
@@ -159,6 +160,7 @@ function printHelp() {
     cmd('aw search <query>', 'Find agents & skills (local + registry)'),
 
     sec('Manage'),
+    cmd('aw docs validate --feature <slug>', 'Validate .aw_docs planning HTML companions before build handoff'),
     cmd('aw status', 'Show synced paths, modified files & conflicts'),
     cmd('aw doctor', 'Run a health check for routing, MCP, plugin, and AW ECC surfaces'),
     cmd('aw link', 'Link current project as a git worktree (wires IDE symlinks)'),

package/codex.mjs

@@ -88,10 +88,19 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 ROOT_DIR="$(cd "\${SCRIPT_DIR}/.." && pwd)"
-TARGET_SCRIPT="\$ROOT_DIR/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
-
-if [[ ! -f "\$TARGET_SCRIPT" ]]; then
-  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW session-start hook not found at .aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh. Run aw pull platform or aw init."}}'
+TARGET_SCRIPT=""
+for candidate in \
+  "\$ROOT_DIR/.aw/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh" \
+  "\$ROOT_DIR/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh"
+do
+  if [[ -f "\$candidate" ]]; then
+    TARGET_SCRIPT="\$candidate"
+    break
+  fi
+done
+
+if [[ -z "\$TARGET_SCRIPT" ]]; then
+  echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW session-start hook not found at .aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh. Run aw pull platform or aw init."}}'
   exit 0
 fi
 

package/commands/c4.mjs

@@ -101,11 +101,13 @@ function safeReaddirSync(dir) {
   try { return readdirSync(dir); } catch { return []; }
 }
 
-function safeListNamespaceDirs(dir) {
+function safeListNamespaceDirs(dir, fsApi = {}) {
+  const readDir = fsApi.readdirSync ?? readdirSync;
+  const stat = fsApi.statSync ?? statSync;
   try {
-    return readdirSync(dir).filter((entry) => {
+    return readDir(dir).filter((entry) => {
       if (entry.startsWith('.')) return false;
-      try { return statSync(join(dir, entry)).isDirectory(); } catch { return false; }
+      try { return stat(join(dir, entry)).isDirectory(); } catch { return false; }
     });
   } catch { return []; }
 }
@@ -132,17 +134,15 @@ function setupGitAuth({ token, c4, home, cwd }) {
   c4.ensureOriginRemote({ cwd });
 }
 
-function resolveCodexRouterSkillPath({ awHome, eccHome, existsSync = fsExistsSync }) {
-  const eccRouterSkillPath = join(eccHome, 'skills/using-aw-skills/SKILL.md');
-  if (existsSync(eccRouterSkillPath)) return eccRouterSkillPath;
-  return join(awHome, '.aw_registry/platform/core/skills/using-aw-skills/SKILL.md');
+function resolveCodexRouterSkillPath({ awHome }) {
+  return join(awHome, '.aw_registry/aw/skills/using-aw-skills/SKILL.md');
 }
 
 /* ─────────────────────────────────────────────────────────────────────────
  * Per-harness branch (step 10).
  *
  * Returns `{ ok, bridge, injector }` so the summary line can pick up
- * codex-specific status ticks. Hard failures (bridge / injector / claude
+ * codex-specific status ticks. Hard failures (injector / claude
  * marketplace / slim card) bubble up as thrown Errors.
  * ───────────────────────────────────────────────────────────────────────── */
 
@@ -165,9 +165,8 @@ function runHarnessBranch({ harness, c4, home, eccHome, cwd, writer, existsSync
   }
   if (harness === 'codex-web') {
     const awHome = join(home, '.aw');
-    c4.applyEccRegistryBridge({ awHome, eccHome });
     c4.ensureCodexHooksFlag(home);
-    const routerSkillPath = resolveCodexRouterSkillPath({ awHome, eccHome, existsSync });
+    const routerSkillPath = resolveCodexRouterSkillPath({ awHome });
     // Pass hookPath explicitly: defaultHookPath() reads os.homedir() at module
     // load time, which ignores the orchestrator's `home` (env.HOME). Without
     // this, installs land in the real ~/.codex even when HOME is overridden
@@ -411,11 +410,11 @@ export async function c4Command(rawArgs, overrides = {}) {
   // check, so we specifically look for directories (namespaces like
   // "platform") to confirm the registry content was actually pulled.
   {
-    const registryNamespaces = safeListNamespaceDirs(awRegistry);
+    const registryNamespaces = safeListNamespaceDirs(awRegistry, fs);
     if (registryNamespaces.length === 0) {
       writer.stderr('[aw-c4] registry has no namespace directories after init — retrying with aw pull\n');
       const pullRes = spawnSync('aw', ['pull'], { stdio: 'pipe' });
-      if (pullRes?.status !== 0 || safeListNamespaceDirs(awRegistry).length === 0) {
+      if (pullRes?.status !== 0 || safeListNamespaceDirs(awRegistry, fs).length === 0) {
         writer.stderr('[aw-c4] FATAL: registry commands were not fetched\n');
         return exit(1);
       }

package/commands/docs.mjs

@@ -0,0 +1,78 @@
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { validateFeatureDocs, normalizeFeatureSlug } from '../aw-docs-validate.mjs';
+
+export async function docsCommand(args) {
+  const subcommand = args._positional?.[0] || 'validate';
+  if (args['--help'] || subcommand === 'help') {
+    printDocsHelp();
+    return;
+  }
+
+  if (!['validate', 'check', 'verify'].includes(subcommand)) {
+    fmt.cancel(`Unknown aw docs command: ${subcommand}\nRun aw docs --help for usage.`);
+  }
+
+  const featureInput = args['--feature'] || args._positional?.[1];
+  let featureSlug = '';
+  try {
+    featureSlug = normalizeFeatureSlug(featureInput);
+  } catch (error) {
+    fmt.cancel(error.message);
+  }
+  if (!featureSlug) {
+    fmt.cancel('Missing feature slug. Use: aw docs validate --feature <feature-slug>');
+  }
+  const result = validateFeatureDocs({
+    cwd: process.cwd(),
+    featureSlug,
+    full: args['--full'] === true,
+    outputMode: args['--output-mode'],
+    publishRequired: args['--publish-required'] === true,
+  });
+
+  if (args['--json'] === true) {
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  fmt.intro('aw docs validate');
+
+  const checked = result.checked.map(item => `  ${item.kind.padEnd(6)} ${chalk.dim(item.source)} -> ${chalk.dim(item.html)}`).join('\n');
+  fmt.note([
+    `${chalk.dim('feature:')}     ${result.featureSlug}`,
+    `${chalk.dim('outputMode:')}  ${result.outputMode}`,
+    `${chalk.dim('checked:')}     ${result.checked.length}`,
+  ].join('\n'), 'Scope');
+
+  if (checked) fmt.note(checked, 'Planning Companions');
+
+  for (const warning of result.warnings) {
+    fmt.logWarn(warning);
+  }
+
+  if (!result.ok) {
+    fmt.note(result.errors.map(error => `  - ${error}`).join('\n'), chalk.red('Blocking Issues'));
+    fmt.cancel('AW docs validation failed. Run platform-core:echo-direct or record an explicit blocker before marking this feature ready.');
+  }
+
+  fmt.outro('⟁  AW docs validation passed');
+}
+
+function printDocsHelp() {
+  console.log([
+    'Usage:',
+    '  aw docs validate --feature <slug> [--full] [--publish-required] [--json]',
+    '  aw docs validate .aw_docs/features/<slug> [--full]',
+    '',
+    'Validates AW planning HTML companions before ready_for_build handoff.',
+    '',
+    'Options:',
+    '  --feature <slug>       Feature slug under .aw_docs/features/',
+    '  --full                 Require prd/design/spec/tasks Markdown and HTML companions',
+    '  --publish-required     Require Devtools/GitHub publish links or a concrete publish blocker',
+    '  --output-mode <mode>   Override docs output mode: dual, html, or markdown',
+    '  --json                 Print machine-readable result',
+  ].join('\n'));
+}

package/commands/doctor.mjs

@@ -548,8 +548,8 @@ function buildDoctorChecks(homeDir, cwd) {
   const rulesDir = resolveRulesDir(homeDir);
 
   const usingAwHookPath = [
-    join(homeDir, '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
-    join(homeDir, '.aw', '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
+    join(homeDir, '.aw_registry', 'aw', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
+    join(homeDir, '.aw', '.aw_registry', 'aw', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
   ].find(existsSync);
 
   checks.push(usingAwHookPath

package/commands/init.mjs

@@ -49,7 +49,16 @@ import {
   syncWorktreeSparseCheckout,
   findNearestWorktree,
 } from '../git.mjs';
-import { REGISTRY_DIR, REGISTRY_REPO, REGISTRY_URL, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, RULES_RUNTIME_DIR } from '../constants.mjs';
+import {
+  REGISTRY_DIR,
+  REGISTRY_REPO,
+  REGISTRY_URL,
+  AW_REGISTRY_NAMESPACE_DIR,
+  DOCS_SOURCE_DIR,
+  AW_DOCS_DIR,
+  RULES_SOURCE_DIR,
+  RULES_RUNTIME_DIR,
+} from '../constants.mjs';
 import { syncFileTree } from '../file-tree.mjs';
 import { installAwUsageHooks, formatAwUsageHooksInstallReport } from '../install-aw-usage-hooks.mjs';
 
@@ -390,7 +399,7 @@ export async function initCommand(args) {
     const isNewSubTeam = folderName && cfg && !cfg.include.includes(folderName);
     if (isNewSubTeam) {
       if (!silent) fmt.logStep(`Adding sub-team ${chalk.cyan(folderName)}...`);
-      const newSparsePaths = [`.aw_registry/${folderName}`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR];
+      const newSparsePaths = [AW_REGISTRY_NAMESPACE_DIR, `.aw_registry/${folderName}`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR];
       addToSparseCheckout(AW_HOME, newSparsePaths);
       config.addPattern(GLOBAL_AW_DIR, folderName);
       scaffoldNamespace(AW_HOME, folderName);
@@ -537,7 +546,7 @@ export async function initCommand(args) {
   }
 
   // Determine sparse paths
-  const sparsePaths = [`.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
+  const sparsePaths = [AW_REGISTRY_NAMESPACE_DIR, `.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
   if (folderName) {
     sparsePaths.push(`.aw_registry/${folderName}`);
   }

package/commands/pull.mjs

@@ -26,6 +26,7 @@ import {
 import {
   REGISTRY_DIR,
   REGISTRY_URL,
+  AW_REGISTRY_NAMESPACE_DIR,
   DOCS_SOURCE_DIR,
   AW_DOCS_DIR,
   RULES_SOURCE_DIR,
@@ -93,7 +94,7 @@ export async function pullCommand(args) {
   // Ensure platform pulls also fetch docs and rules on older installs that
   // pre-date the new sparse-checkout paths.
   if (input === 'platform') {
-    addToSparseCheckout(AW_HOME, [`.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR]);
+    addToSparseCheckout(AW_HOME, [AW_REGISTRY_NAMESPACE_DIR, `.aw_registry/platform`, DOCS_SOURCE_DIR, AW_DOCS_DIR, RULES_SOURCE_DIR]);
     if (!cfg.include.includes('platform')) {
       config.addPattern(GLOBAL_AW_DIR, 'platform');
     }

package/constants.mjs

@@ -19,6 +19,9 @@ export const REGISTRY_URL = process.env.AW_REGISTRY_URL
 /** Directory inside the registry repo that holds platform/ and [template]/ */
 export const REGISTRY_DIR = '.aw_registry';
 
+/** Top-level AW namespace in the registry. Holds active AW-owned skills. */
+export const AW_REGISTRY_NAMESPACE_DIR = `${REGISTRY_DIR}/aw`;
+
 /** Directory in platform-docs repo containing documentation (pulled into platform/docs/) */
 export const DOCS_SOURCE_DIR = 'content';
 

package/ecc.mjs

@@ -12,7 +12,7 @@ import { applyStoredStartupPreferences } from "./startup.mjs";
 
 const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
 const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
-export const AW_ECC_TAG = "v1.4.65";
+export const AW_ECC_TAG = "v1.4.66";
 const REQUIRED_ECC_FILES = [
   "package.json",
   "scripts/install-apply.js",
@@ -24,19 +24,33 @@ const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
 
 function eccDir() { return join(homedir(), ".aw-ecc"); }
 
-// "claude" uses a no-commands module set so hooks, rules, shared references,
-// and install-state land in ~/.claude/ — while slash commands stay owned by
-// the marketplace plugin under /aw:*.
+// File-copy targets use explicit non-skill module sets so hooks, rules,
+// command compatibility, shared references, and install-state can remain
+// available while AW skills come from platform-docs/.aw_registry/aw.
 // Using `--without baseline:commands` with broader profiles is unsafe because
 // some optional modules depend on commands-core and cause install-apply to fail.
 const FILE_COPY_TARGETS = ["claude", "cursor", "codex"];
-const CLAUDE_FILE_COPY_MODULES = [
-  "rules-core",
-  "agents-core",
-  "hooks-runtime",
-  "platform-configs",
-  "workflow-quality",
-];
+const FILE_COPY_MODULES_BY_TARGET = {
+  claude: [
+    "rules-core",
+    "agents-core",
+    "hooks-runtime",
+    "platform-configs",
+  ],
+  cursor: [
+    "rules-core",
+    "agents-core",
+    "commands-core",
+    "hooks-runtime",
+    "platform-configs",
+  ],
+  codex: [
+    "rules-core",
+    "agents-core",
+    "hooks-runtime",
+    "platform-configs",
+  ],
+};
 
 const TARGET_STATE = {
   claude: { state: ".claude/ecc/install-state.json" },
@@ -246,7 +260,6 @@ function cloneOrUpdate(tag, dest) {
  */
 function transformCursorAwRefs(home) {
   const dirs = [
-    join(home, ".cursor", "skills"),
     join(home, ".cursor", "rules"),
   ];
   for (const dir of dirs) {
@@ -320,16 +333,38 @@ function namespaceCursorCommands(home) {
 }
 
 /**
- * Run scripts/sync-ecc-to-codex.sh from the cloned ecc repo.
- * Generates ~/.codex/prompts/*.md (Codex equivalent of slash commands),
- * using aw-*.md for AW-namespaced commands and ecc-*.md for the rest,
- * and merges ~/.codex/AGENTS.md. Best-effort — failure doesn't block init.
+ * Generate Codex prompt files from ECC commands only.
+ *
+ * The old ECC sync script also materialized ECC skills into Codex-owned
+ * skill directories. AW skills now come from platform-docs/.aw_registry/aw,
+ * so this runtime keeps the command prompt compatibility surface and does
+ * not run the broad ECC skill sync.
  */
-function syncEccToCodex(repoDir) {
-  const syncScript = join(repoDir, "scripts", "sync-ecc-to-codex.sh");
-  if (!existsSync(syncScript)) return;
+function syncEccCommandsToCodex(repoDir) {
+  const commandsDir = join(repoDir, "commands");
+  if (!existsSync(commandsDir)) return;
   try {
-    run(`bash "${syncScript}"`, { cwd: homedir() });
+    const promptsDir = join(homedir(), ".codex", "prompts");
+    mkdirSync(promptsDir, { recursive: true });
+    const manifest = [];
+
+    for (const file of readdirSync(commandsDir).filter((entry) => entry.endsWith(".md") && !entry.startsWith("."))) {
+      const commandPath = join(commandsDir, file);
+      const content = readFileSync(commandPath, "utf8");
+      const basename = file.replace(/\.md$/, "");
+      const heading = content.match(/^#\s+(\/\S+)/m)?.[1];
+      const promptName = heading?.startsWith("/aw:")
+        ? heading.slice(1).replace(/:/g, "-").replace(/[^\w.-]/g, "-")
+        : `ecc-${basename}`;
+      const promptFile = `${promptName}.md`;
+      writeFileSync(join(promptsDir, promptFile), content);
+      manifest.push(promptFile);
+    }
+
+    writeFileSync(
+      join(promptsDir, "ecc-prompts-manifest.txt"),
+      manifest.sort().map((entry) => `${entry}\n`).join(""),
+    );
   } catch { /* best effort — codex sync failure is non-blocking */ }
 }
 
@@ -381,9 +416,10 @@ export async function installAwEcc(
 
           // Always use HOME as cwd so files land in ~/.<target>/ globally.
           const runCwd = homedir();
-          const installArgs = target === "claude"
-            ? `--target ${target} --modules ${CLAUDE_FILE_COPY_MODULES.join(",")}`
-            : `--target ${target} --profile full`;
+          const installModules = FILE_COPY_MODULES_BY_TARGET[target] || [];
+          const installArgs = installModules.length > 0
+            ? `--target ${target} --modules ${installModules.join(",")}`
+            : `--target ${target}`;
           run(
             `node ${join(repoDir, "scripts/install-apply.js")} ${installArgs}`,
             { cwd: runCwd },
@@ -393,7 +429,7 @@ export async function installAwEcc(
             transformCursorAwRefs(home);
           }
           if (target === "codex") {
-            syncEccToCodex(repoDir);
+            syncEccCommandsToCodex(repoDir);
           }
           restoreProtectedConfigs(snapshot);
         } catch { /* target not supported — skip */ }

package/git.mjs

@@ -5,7 +5,14 @@ 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, AW_DOCS_DIR, RULES_SOURCE_DIR } from './constants.mjs';
+import {
+  REGISTRY_BASE_BRANCH,
+  REGISTRY_DIR,
+  AW_REGISTRY_NAMESPACE_DIR,
+  DOCS_SOURCE_DIR,
+  AW_DOCS_DIR,
+  RULES_SOURCE_DIR,
+} from './constants.mjs';
 
 const exec = promisify(execCb);
 
@@ -155,6 +162,7 @@ export function includeToSparsePaths(paths) {
   }
   result.add(`${REGISTRY_DIR}/AW-PROTOCOL.md`);
   if (paths.includes('platform')) {
+    result.add(AW_REGISTRY_NAMESPACE_DIR);
     result.add(DOCS_SOURCE_DIR);
     result.add(AW_DOCS_DIR);
     result.add(RULES_SOURCE_DIR);
@@ -389,14 +397,9 @@ export async function fetchAndMerge(awHome, { silent = true } = {}) {
   // git 2.46+ bug on blob:none + no-cone sparse-checkout repos that silently
   // drops bare-name patterns (e.g. "content", "CODEOWNERS") when HEAD advances.
   //
-  // --autostash: AW writes into the registry working tree from external
-  // sources (ensureAwRuntimeHook copies ~/.aw-ecc/.../session-start.sh into a
-  // tracked path; transformCursorAwRefs rewrites /aw: → /aw- through Cursor
-  // skill directory symlinks that resolve into .aw_registry/). When those
-  // versions drift, the working tree is dirty at rebase time and rebase
-  // refuses to run, silently aborting the entire pull. Autostash stashes the
-  // dirty bytes, rebases cleanly, and reapplies them — so the registry stays
-  // in sync even when external sources have leaked into the tracked tree.
+  // --autostash: AW can have local registry edits pending when sync runs.
+  // Without autostash, git refuses to rebase and the pull silently aborts.
+  // Autostash stashes dirty bytes, rebases cleanly, and reapplies them.
   try {
     await exec(`git -C "${awHome}" rebase --autostash origin/${REGISTRY_BASE_BRANCH}`);
     updated = true;

package/hooks/codex-home.mjs

@@ -26,10 +26,10 @@ const CODEX_HOME_PHASE_BLUEPRINTS = {
         marker: this.scriptMarker,
         phase: 'SessionStart',
         targetCandidates: [
-          '$HOME/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh',
-          '$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh',
+          '$HOME/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh',
+          '$HOME/.aw/.aw_registry/aw/skills/using-aw-skills/hooks/session-start.sh',
         ],
-        warningMessage: 'WARNING: AW using-aw-skills hook not found in ~/.aw_registry. Run aw init or aw pull platform.',
+        warningMessage: 'WARNING: AW using-aw-skills hook not found in ~/.aw_registry/aw. Run aw init or aw pull platform.',
         telemetryHookPath: '$HOME/.aw-ecc/scripts/hooks/aw-usage-session-start.js',
         harnessEnv: 'codex',
       });

package/link.mjs

@@ -158,10 +158,12 @@ function cleanSymlinksRecursive(dir) {
 }
 
 /**
- * Compute flat IDE name: namespace-slug (always includes namespace).
+ * Compute flat IDE names. The top-level `aw` namespace is already encoded in
+ * its skill and command names, so keep those names stable instead of producing
+ * aw-aw-plan or aw-plan.md variants.
  */
-function flatName(ns, name) {
-  return `${ns}-${name}`;
+function flatRegistryName(ns, ...parts) {
+  return (ns === 'aw' ? parts : [ns, ...parts]).join('-');
 }
 
 /**
@@ -202,7 +204,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
     for (const type of FILE_TYPES) {
       for (const { typeDirPath, segments } of findNestedTypeDirs(join(awDir, ns), type)) {
         for (const file of readdirSync(typeDirPath).filter(f => f.endsWith('.md') && !f.startsWith('.'))) {
-          const flat = [ns, ...segments, file].join('-');
+          const flat = flatRegistryName(ns, ...segments, file);
 
           for (const ide of IDE_DIRS) {
             const linkDir = join(cwd, ide, type);
@@ -219,7 +221,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
     // Skills: per-skill directory symlinks (recursive for nested domain dirs)
     for (const { typeDirPath: skillsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'skills')) {
       for (const skill of listDirs(skillsDir)) {
-        const flat = [ns, ...segments, skill].join('-');
+        const flat = flatRegistryName(ns, ...segments, skill);
 
         for (const ide of IDE_DIRS) {
           const linkDir = join(cwd, ide, 'skills');
@@ -233,7 +235,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
 
       for (const { skillDirPath, segments: skillSegments } of findSkillRootDirs(skillsDir)) {
         if (skillSegments.length <= 1) continue;
-        const flat = [ns, ...segments, ...skillSegments].join('-');
+        const flat = flatRegistryName(ns, ...segments, ...skillSegments);
 
         for (const ide of IDE_DIRS) {
           const linkDir = join(cwd, ide, 'skills');
@@ -254,7 +256,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
       if (isColocated) {
         // Colocated evals: agents/evals/<slug>/ — one level of slug dirs
         for (const evalSlug of listDirs(evalsDir)) {
-          const flat = [ns, ...segments, evalSlug].join('-');
+          const flat = flatRegistryName(ns, ...segments, evalSlug);
           for (const ide of IDE_DIRS) {
             const linkDir = join(cwd, ide, 'evals');
             mkdirSync(linkDir, { recursive: true });
@@ -269,7 +271,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
         for (const subType of listDirs(evalsDir)) {
           const subDir = join(evalsDir, subType);
           for (const evalName of listDirs(subDir)) {
-            const flat = [ns, ...segments, subType, evalName].join('-');
+            const flat = flatRegistryName(ns, ...segments, subType, evalName);
             for (const ide of IDE_DIRS) {
               const linkDir = join(cwd, ide, 'evals');
               mkdirSync(linkDir, { recursive: true });
@@ -310,7 +312,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
       for (const { typeDirPath: skillsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'skills')) {
         mkdirSync(agentsSkillsDir, { recursive: true });
         for (const skill of listDirs(skillsDir)) {
-          const flat = [ns, ...segments, skill].join('-');
+          const flat = flatRegistryName(ns, ...segments, skill);
           const linkPath = join(agentsSkillsDir, flat);
           const targetPath = join(skillsDir, skill);
           const relTarget = relative(agentsSkillsDir, targetPath);
@@ -319,7 +321,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
 
         for (const { skillDirPath, segments: skillSegments } of findSkillRootDirs(skillsDir)) {
           if (skillSegments.length <= 1) continue;
-          const flat = [ns, ...segments, ...skillSegments].join('-');
+          const flat = flatRegistryName(ns, ...segments, ...skillSegments);
           const linkPath = join(agentsSkillsDir, flat);
           const relTarget = relative(agentsSkillsDir, skillDirPath);
           if (linkNestedSkillRoot(relTarget, linkPath, { silent })) created++;
@@ -346,7 +348,7 @@ export function linkWorkspace(cwd, awDirOverride = null, { silent = false } = {}
   for (const ns of namespaces) {
     for (const { typeDirPath: commandsDir, segments } of findNestedTypeDirs(join(awDir, ns), 'commands')) {
       for (const file of readdirSync(commandsDir).filter(f => f.endsWith('.md') && !f.startsWith('.'))) {
-        const cmdFileName = [ns, ...segments, file].join('-');
+        const cmdFileName = flatRegistryName(ns, ...segments, file);
 
         for (const ide of IDE_DIRS) {
           const linkDir = join(cwd, ide, 'commands', 'aw');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.68",
+  "version": "0.1.70-beta.0",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {
@@ -29,6 +29,7 @@
     "slack-sim/",
     "file-tree.mjs",
     "apply.mjs",
+    "aw-docs-validate.mjs",
     "hook-cleanup.mjs",
     "hook-manifest.mjs",
     "update.mjs",

package/startup.mjs

@@ -83,8 +83,10 @@ function resolveRegistryRoot(homeDir = homedir()) {
   ].find(existsSync) || null;
 }
 
-function awRuntimeHookSourcePath(homeDir = homedir()) {
-  return join(homeDir, '.aw-ecc', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh');
+function awRuntimeHookDestinationPath(homeDir = homedir()) {
+  const registryRoot = resolveRegistryRoot(homeDir);
+  if (!registryRoot) return null;
+  return join(registryRoot, 'aw', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh');
 }
 
 function readJson(filePath, fallback = {}) {
@@ -393,27 +395,10 @@ function hasCodexSessionStartScript(homeDir = homedir()) {
 }
 
 export function ensureAwRuntimeHook(homeDir = homedir()) {
-  const sourcePath = awRuntimeHookSourcePath(homeDir);
-  const registryRoot = resolveRegistryRoot(homeDir);
-  if (!existsSync(sourcePath) || !registryRoot) return [];
-
-  const destinationPath = join(
-    registryRoot,
-    'platform',
-    'core',
-    'skills',
-    'using-aw-skills',
-    'hooks',
-    'session-start.sh',
-  );
-  const sourceContent = readFileSync(sourcePath, 'utf8');
-  const existingContent = existsSync(destinationPath) ? readFileSync(destinationPath, 'utf8') : null;
-  if (existingContent === sourceContent) return [];
-
-  mkdirSync(dirname(destinationPath), { recursive: true });
-  writeFileSync(destinationPath, sourceContent);
+  const destinationPath = awRuntimeHookDestinationPath(homeDir);
+  if (!destinationPath || !existsSync(destinationPath)) return [];
   try { chmodSync(destinationPath, 0o755); } catch { /* best effort */ }
-  return [destinationPath];
+  return [];
 }
 
 function hasCodexHooksEnabled(homeDir = homedir()) {

package/c4/eccRegistryBridge.mjs

@@ -1,236 +0,0 @@
-/**
- * c4/eccRegistryBridge.mjs — Codex-only Bug A workaround.
- *
- * Codex Web's upstream `aw-session-start.sh` enumerator scans a fixed
- * registry path:
- *
- *   ~/.aw/.aw_registry/platform/core/skills/<name>/SKILL.md
- *
- * ECC ships skills under a different path:
- *
- *   ~/.aw-ecc/skills/<name>/SKILL.md
- *
- * On Codex Web, neither Claude's plugin marketplace nor Cursor's direct
- * `~/.cursor/skills/...` resolution applies. The only way Codex can see
- * ECC skills is if the registry path is populated. We bridge by symlinking
- * each ECC skill's SKILL.md into the registry layout. The default mode keeps
- * the original non-clobbering behavior. `preferEccSkills` only retargets
- * existing symlinks; regular files are treated as user-owned and preserved.
- *
- * Also installs a fallback symlink at `<homeOf(awHome)>/.aw_registry` →
- * `<awHome>/.aw_registry` because some legacy hooks read from that path.
- *
- * **Scope**: Codex Web only. The orchestrator is responsible for *not*
- * invoking this on claude-web or cursor-cloud; the module itself is
- * harness-agnostic and just performs the bridge.
- */
-
-import {
-  existsSync,
-  lstatSync,
-  readlinkSync,
-  readdirSync,
-  mkdirSync,
-  symlinkSync,
-  unlinkSync,
-} from 'node:fs';
-import { dirname, join } from 'node:path';
-
-/** True iff `path` is a symlink that points to a nonexistent target. */
-function isBrokenSymlink(path) {
-  try {
-    const st = lstatSync(path);
-    if (!st.isSymbolicLink()) return false;
-    return !existsSync(path);
-  } catch {
-    return false;
-  }
-}
-
-/** True iff `path` is a symlink that already points at `target`. */
-function isSymlinkTo(path, target) {
-  try {
-    const st = lstatSync(path);
-    if (!st.isSymbolicLink()) return false;
-    return readlinkSync(path) === target;
-  } catch {
-    return false;
-  }
-}
-
-/** True iff `path` is any symlink, regardless of where it points. */
-function isSymlink(path) {
-  try {
-    return lstatSync(path).isSymbolicLink();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Install the fallback symlink `~/.aw_registry → ~/.aw/.aw_registry` if not
- * present and not blocked by an existing real directory. Best-effort.
- */
-function installRegistryFallbackLink(awHome) {
-  const home = dirname(awHome);
-  const fallback = join(home, '.aw_registry');
-  const target = join(awHome, '.aw_registry');
-
-  if (!existsSync(target)) {
-    // Nothing to point at yet — skip silently.
-    return;
-  }
-
-  let existsAtFallback = false;
-  try {
-    lstatSync(fallback);
-    existsAtFallback = true;
-  } catch {
-    existsAtFallback = false;
-  }
-
-  if (existsAtFallback) return; // do not clobber existing dir/symlink
-
-  try {
-    symlinkSync(target, fallback);
-  } catch {
-    // best-effort
-  }
-}
-
-/**
- * Symlink every ECC skill into the registry layout. Idempotent.
- *
- * Result shape:
- *   - linked   — skill names freshly bridged this call
- *   - skipped  — skill names whose registry target already existed and was preserved
- *   - replaced — skill names whose registry target was replaced with the ECC symlink
- *   - broken   — skill directories that exist in eccHome/skills/ but have no SKILL.md
- *                (broken ECC layout — distinct from already-bridged so the orchestrator
- *                can surface a real diagnostic rather than treating it as success)
- *   - reason   — only set when the result is fully diagnostic:
- *                  'ecc-missing'    — eccHome/skills/ does not exist
- *                  'already-bridged' — every well-formed skill was already linked
- *                                     and there were no broken skills
- *
- * @param {object} opts
- * @param {string} opts.awHome    Path of the AW home (e.g. ~/.aw).
- * @param {string} opts.eccHome   Path of the ECC home (e.g. ~/.aw-ecc).
- * @param {boolean} [opts.preferEccSkills=false]
- *   Retarget existing registry SKILL.md symlinks to ECC. Regular files are
- *   never replaced because they may be user-owned overrides.
- * @returns {{
- *   linked: string[],
- *   skipped: string[],
- *   replaced: string[],
- *   broken: string[],
- *   reason?: 'already-bridged' | 'ecc-missing'
- * }}
- */
-export function applyEccRegistryBridge({ awHome, eccHome, preferEccSkills = false } = {}) {
-  if (!awHome || !eccHome) {
-    throw new Error('applyEccRegistryBridge: awHome and eccHome are required');
-  }
-
-  const eccSkillsDir = join(eccHome, 'skills');
-  if (!existsSync(eccSkillsDir)) {
-    return { linked: [], skipped: [], broken: [], reason: 'ecc-missing' };
-  }
-
-  const linked = [];
-  const skipped = [];
-  const replaced = [];
-  const broken = [];
-
-  let entries;
-  try {
-    entries = readdirSync(eccSkillsDir, { withFileTypes: true });
-  } catch {
-    return { linked: [], skipped: [], broken: [], reason: 'ecc-missing' };
-  }
-
-  let skillDirCount = 0;
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    skillDirCount += 1;
-    const name = entry.name;
-    const source = join(eccSkillsDir, name, 'SKILL.md');
-
-    // ECC skill directory exists but lacks SKILL.md → broken layout.
-    if (!existsSync(source)) {
-      broken.push(name);
-      continue;
-    }
-
-    const targetDir = join(awHome, '.aw_registry/platform/core/skills', name);
-    const target = join(targetDir, 'SKILL.md');
-
-    // If target already exists and is healthy, preserve regular files. The
-    // optional preference mode may only retarget generated symlinks; it must
-    // not delete user-owned registry files.
-    let targetExists = false;
-    try {
-      lstatSync(target);
-      targetExists = true;
-    } catch {
-      targetExists = false;
-    }
-
-    if (targetExists && !isBrokenSymlink(target)) {
-      if (isSymlinkTo(target, source)) {
-        skipped.push(name);
-        continue;
-      }
-
-      if (!preferEccSkills || !isSymlink(target)) {
-        skipped.push(name);
-        continue;
-      }
-
-      try {
-        unlinkSync(target);
-      } catch {
-        broken.push(name);
-        continue;
-      }
-
-      try {
-        symlinkSync(source, target);
-        replaced.push(name);
-      } catch {
-        broken.push(name);
-      }
-      continue;
-    }
-
-    // Either absent or a broken symlink — replace.
-    mkdirSync(targetDir, { recursive: true });
-    if (targetExists) {
-      try { unlinkSync(target); } catch { /* best-effort */ }
-    }
-    try {
-      symlinkSync(source, target);
-      linked.push(name);
-    } catch {
-      // Filesystem may forbid symlinks (rare on Codex Web). Treat as broken
-      // so the orchestrator can surface the real diagnostic.
-      broken.push(name);
-    }
-  }
-
-  installRegistryFallbackLink(awHome);
-
-  const result = { linked, skipped, replaced, broken };
-  // Only flag 'already-bridged' when every well-formed skill was already linked
-  // AND no broken skills exist — i.e. this run was a true no-op.
-  if (
-    skillDirCount > 0 &&
-    linked.length === 0 &&
-    replaced.length === 0 &&
-    broken.length === 0 &&
-    skipped.length === skillDirCount
-  ) {
-    result.reason = 'already-bridged';
-  }
-  return result;
-}