fix: address code review issues in Codex build script and docs

Build script:
- Escape backslashes before quotes in YAML output
- Handle Windows-style line endings in frontmatter parsing
- Use dir.name (not fm.name) for display_name consistency
- Warn when openai.yaml is skipped due to missing frontmatter
- Compute actual skipped count from filesystem, not set size

Docs:
- Add Deno prerequisite
- Clarify that axiom-codex/ is created by the build step
- Remove unverified $skill-name invocation syntax
- Add Troubleshooting section
- Improve Also Available with relationship explanations
- Change "Not yet supported" to "Not supported" for accuracy

docs/guide/codex-install.md

@@ -19,6 +19,7 @@ The Codex plugin includes 164 specialized skills covering:
 ## Prerequisites
 
 - **Codex CLI** or Codex web app
+- **Deno** — required to build the plugin. Check with `deno --version` or install from [deno.com](https://deno.com)
 
 ## Installation
 
@@ -36,6 +37,8 @@ cd Axiom
 npm run build:codex
 ```
 
+This creates the `axiom-codex/` directory containing the plugin. Use its full path in the config below.
+
 Add to your personal marketplace at `~/.agents/plugins/marketplace.json`:
 
 ```json
@@ -91,8 +94,6 @@ Skills activate automatically based on your questions. Just ask:
 "I need to add a database column safely"
 ```
 
-You can also invoke skills explicitly with `$skill-name` in Codex.
-
 ## Updating
 
 Pull the latest changes and rebuild:
@@ -112,14 +113,35 @@ The Codex plugin includes the same skill content as the Claude Code plugin, with
 | Feature | Claude Code | Codex |
 |---------|-------------|-------|
 | Skills | 164 specialized + 17 routers | 164 specialized (Codex has native routing) |
-| Agents | 38 autonomous auditors | Not yet supported in Codex plugins |
-| Commands | 12 `/axiom:*` commands | Not yet supported in Codex plugins |
+| Agents | 38 autonomous auditors | Not supported in Codex plugins |
+| Commands | 12 `/axiom:*` commands | Not supported in Codex plugins |
 | Installation | `/plugin marketplace add` | Local marketplace |
 
-As the Codex plugin system matures, we'll add support for additional features.
+## Troubleshooting
+
+### `deno: command not found`
+
+Install Deno from [deno.com](https://deno.com):
+
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+```
+
+### `axiom-codex/` directory not found
+
+Run the build step first:
+
+```bash
+cd /path/to/Axiom
+npm run build:codex
+```
+
+### Skills not appearing in Codex
+
+Verify the path in your `marketplace.json` points to the `axiom-codex/` directory (not the repo root), and that the directory contains `.codex-plugin/plugin.json`.
 
 ## Also Available
 
-- **[Claude Code](/guide/quick-start)** — Native plugin with full agent and command support
-- **[MCP Server](/guide/mcp-install)** — Works with VS Code, Cursor, Gemini CLI, and more
-- **[Xcode Integration](/guide/xcode-setup)** — Direct Xcode MCP bridge setup
+- **[Claude Code](/guide/quick-start)** — Full Axiom experience with 38 autonomous agents and 12 commands
+- **[MCP Server](/guide/mcp-install)** — Skills in VS Code, Cursor, Gemini CLI, and any MCP-compatible tool; no build step required
+- **[Xcode Integration](/guide/xcode-setup)** — Direct Xcode MCP bridge for in-editor assistance

scripts/build-codex.ts

@@ -48,10 +48,10 @@ fs.mkdirSync(OUTPUT_MANIFEST, { recursive: true });
 
 // Parse SKILL.md frontmatter (name, description) without external dependencies
 function parseFrontmatter(content: string): Record<string, string> {
-  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!match) return {};
   const fields: Record<string, string> = {};
-  for (const line of match[1].split('\n')) {
+  for (const line of match[1].split(/\r?\n/)) {
     const m = line.match(/^(\w+):\s*(.+)/);
     if (m) fields[m[1]] = m[2];
   }
@@ -91,8 +91,8 @@ function toShortDescription(description: string): string {
   const end = short.search(/\.\s|—|\s-\s/);
   if (end >= 20) short = short.slice(0, end);
   if (short.length > 120) short = short.slice(0, 117) + '...';
-  // Escape quotes for YAML and trim
-  short = short.replace(/"/g, '\\"').trim();
+  // Escape for YAML double-quoted string (backslashes first, then quotes) and trim
+  short = short.replace(/\\/g, '\\\\').replace(/"/g, '\\"').trim();
   return short.charAt(0).toUpperCase() + short.slice(1);
 }
 
@@ -117,11 +117,13 @@ for (const dir of skillDirs) {
     fs.mkdirSync(agentsDir, { recursive: true });
     const yaml = [
       'interface:',
-      `  display_name: "${toDisplayName(fm.name)}"`,
+      `  display_name: "${toDisplayName(dir.name)}"`,
       `  short_description: "${toShortDescription(fm.description)}"`,
       '',
     ].join('\n');
     fs.writeFileSync(path.join(agentsDir, 'openai.yaml'), yaml);
+  } else {
+    console.warn(`  warn: skipped openai.yaml for ${dir.name} (missing name or description in frontmatter)`);
   }
 
   copied++;
@@ -163,5 +165,6 @@ fs.writeFileSync(
 );
 
 // Summary
-const skipped = EXCLUDE_SKILLS.size;
+const allDirs = fs.readdirSync(SOURCE_SKILLS, { withFileTypes: true }).filter(d => d.isDirectory());
+const skipped = allDirs.filter(d => EXCLUDE_SKILLS.has(d.name)).length;
 console.log(`axiom-codex built: ${copied} skills (${skipped} routers excluded), v${version}`);