AI Guide Renderer README

This directory (community/.ai) contains the templates and documentation source used by:

node community/.ai/render-guides.mjs

The renderer produces guide files (AGENTS.md, CLAUDE.md), skill stubs, and OpenCode config/skills.

Quick run

node community/.ai/render-guides.mjs

Force edition when needed:

AI_GUIDE_EDITION=COMMUNITY node community/.ai/render-guides.mjs
AI_GUIDE_EDITION=ULTIMATE  node community/.ai/render-guides.mjs

What is generated

• AGENTS.md
• community/AGENTS.md (generated in ultimate workspace)
• CLAUDE.md (ultimate only)
• opencode.json (from .mcp.json)
• .opencode/skill/* (mirrored from .codex/skills/*)
• Skill stubs in .agents/skills/*, .claude/skills/*, community/.claude/skills/*

High-level render pipeline

                community/.ai/guide.md
                         |
                         | inject partials + compilation rule
                         v
      +---------------------------------------------+
      | template transforms                          |
      | - rewrite markdown links                     |
      | - apply IF_TOOL blocks                       |
      | - apply IF_EDITION blocks                    |
      | - strip TEMPLATE:COMMENT blocks              |
      | - normalize whitespace                        |
      +----------------------+----------------------+
                             |
                             +--> AGENTS.md
                             +--> community/AGENTS.md (ultimate workspace)
                             +--> CLAUDE.md (ultimate only)
                             +--> opencode.json
                             +--> .opencode/skill/*
                             +--> skill stubs (see next section)

Skill sources and stub generation

The renderer has two skill sources:

1. Community source skills: community/.agents/skills/*/SKILL.md
2. Ultimate-only source skills: manual (non-generated) .agents/skills/*/SKILL.md

Generated stubs are recognized by marker:

<!-- Generated by community/.ai/render-guides.mjs; edit ... -->

Manual files in .agents/skills/ without that marker are treated as ultimate-only sources.

PASS 1 (community source skills)
--------------------------------
community/.agents/skills/<name>/SKILL.md
   |--> .agents/skills/<name>/SKILL.md
   |--> .claude/skills/<name>/SKILL.md
   '--> community/.claude/skills/<name>/SKILL.md

PASS 2 (ultimate-only manual skills)
------------------------------------
.agents/skills/<name>/SKILL.md   [manual, non-generated]
   '--> .claude/skills/<name>/SKILL.md   [ULTIMATE only]

Cleanup
-------
Generated stubs not in the expected set are pruned.
Only generated stubs are deleted. Manual files are preserved.

Edition behavior

Edition resolution order:

1. AI_GUIDE_EDITION
2. RENDER_EDITION
3. .ultimate.root.marker presence (ULTIMATE if present, else COMMUNITY)

Accepted values: COMMUNITY, ULTIMATE.

Edition impact:

• ULTIMATE
  • pass-2 runs (ultimate-only skills can generate .claude/skills/* stubs)
• COMMUNITY
  • pass-2 is skipped
  • stale generated ultimate-only stubs are pruned from .claude/skills/

Template model

• Main template: community/.ai/guide.md
• Local partials: community/.ai/partials/*.md
• Shared partial overrides: .ai/partials/*.md

Template directives

Tool gating:

<!-- IF_TOOL:CODEX -->
... only in Codex outputs ...
<!-- /IF_TOOL:CODEX -->

Edition gating:

<!-- IF_EDITION:ULTIMATE -->
... only in ultimate outputs ...
<!-- /IF_EDITION:ULTIMATE -->

Template-only comments (removed in outputs):

<!-- TEMPLATE:COMMENT -->
internal notes only
<!-- /TEMPLATE:COMMENT -->

Required placeholders

• {{FORBIDDEN_TOOLS_SUFFIX}} is filled per output target.

If placeholders remain after rendering, the renderer fails fast.

Validation and tests

• Renderer test: community/.ai/render-guides.test.mjs

Run:

node --test community/.ai/render-guides.test.mjs

Troubleshooting

• Unknown partial: ...
  • Check partial filename and {{PARTIAL:name}} token spelling.
• Unexpected missing content in output
  • Check IF_TOOL / IF_EDITION guards and selected edition.
• Broken relative links in generated files
  • Source links were likely moved; rerender and verify rewritten targets.
• Stale skill directory still present
  • If it has no generated marker, cleanup intentionally preserves it.