Module templating 

Markdown templating engine for AGPM resources.

This module provides Tera-based templating functionality for Markdown resources, enabling dynamic content generation during installation. It supports safe, sandboxed template rendering with a rich context containing installation metadata.

Overview

The templating system allows resource authors to:

• Reference other resources by name and type
• Access resolved installation paths and versions
• Use conditional logic and loops in templates
• Read and embed project-specific files (style guides, best practices, etc.)

Template Context

Templates are rendered with a structured context containing:

• agpm.resource: Current resource information (name, type, install path, etc.)
• agpm.deps: Nested dependency information by resource type and name

Custom Filters

• content: Read project-specific files (e.g., {{ 'docs/guide.md' | content }})

Syntax Restrictions

For security and safety, the following Tera features are disabled:

• {% include %} tags (no file system access)
• {% extends %} tags (no template inheritance)
• {% import %} tags (no external template imports)
• Custom functions that access the file system or network (except content filter)

Supported Features

• Variable substitution: {{ agpm.resource.install_path }}
• Conditional logic: {% if agpm.resource.source %}...{% endif %}
• Loops: {% for name, dep in agpm.deps.agents %}...{% endfor %}
• Standard Tera filters (string manipulation, formatting)
• Project file embedding: {{ 'path/to/file.md' | content }}
• Literal blocks: Protect template syntax from rendering for documentation

Literal Blocks (Documentation Mode)

When writing documentation that includes template syntax examples, you can use literal fenced code blocks to protect the content from being rendered:

# Template Documentation

Here's how to use template variables:

```literal
{{ agpm.deps.snippets.example.content }}
```

The above syntax will be displayed literally, not rendered.

This is particularly useful for:

• Documentation snippets that show template syntax examples
• Tutorial content that explains how to use templates
• Example code that should not be executed during rendering

The content inside literal blocks will be:

1. Protected from template rendering (preserved as-is)
2. Wrapped in standard markdown code fences in the output
3. Displayed literally to the end user

Examples

Basic Variable Substitution

# {{ agpm.resource.name }}

This agent is installed at: `{{ agpm.resource.install_path }}`
Version: {{ agpm.resource.version }}

Dependency Content Embedding (v0.4.7+)

All dependencies automatically have .content field with processed content:

---
agpm.templating: true
dependencies:
  snippets:
    - path: snippets/best-practices.md
      name: best_practices
---
# Code Reviewer

## Best Practices
{{ agpm.deps.snippets.best_practices.content }}

Project File Filter (v0.4.8+)

Read project-specific files using the content filter:

---
agpm.templating: true
---
# Team Agent

## Project Style Guide
{{ 'project/styleguide.md' | content }}

## Team Conventions
{{ 'docs/conventions.txt' | content }}

Combining Dependency Content + Project Files

Use both features together for maximum flexibility:

---
agpm.templating: true
dependencies:
  snippets:
    - path: snippets/rust-patterns.md
      name: rust_patterns
    - path: snippets/error-handling.md
      name: error_handling
---
# Rust Code Reviewer

## Shared Patterns (from AGPM repository)
{{ agpm.deps.snippets.rust_patterns.content }}

## Project-Specific Style Guide
{{ 'project/rust-style.md' | content }}

## Error Handling Best Practices
{{ agpm.deps.snippets.error_handling.content }}

## Team Conventions
{{ 'docs/team-conventions.txt' | content }}

When to use each:

• Dependency content: Versioned, shared resources from AGPM repos
• Project files: Team-specific, project-local documentation

Literal Blocks for Documentation

When creating documentation snippets that explain template syntax, use literal blocks to prevent the examples from being rendered:

---
agpm.templating: true
---
# AGPM Template Guide

## How to Embed Snippet Content

To embed a snippet's content in your template, use this syntax:

```literal
{{ agpm.deps.snippets.best_practices.content }}
```

This will render the **current agent name**: {{ agpm.resource.name }}

## How to Loop Over Dependencies

```literal
{% for name, dep in agpm.deps.agents %}
- {{ name }}: {{ dep.version }}
{% endfor %}
```

The syntax examples above are displayed literally, while the agent name
below is dynamically rendered based on the context.

In this example:

• The literal blocks show template syntax examples without rendering them
• Regular template variables like {{ agpm.resource.name }} are still rendered
• This allows documentation to demonstrate template features while using them

Recursive Project Files

Project files can reference other project files (up to 10 levels):

Main agent (.claude/agents/reviewer.md):

---
agpm.templating: true
---
# Code Reviewer

{{ 'project/styleguide.md' | content }}

Style guide (project/styleguide.md):

# Coding Standards

## Rust-Specific Rules
{{ 'project/rust-style.md' | content }}

Dependency References

Dependencies are accessible by name in the template context. The name is determined by:

1. For manifest deps: the key in [agents], [snippets], etc.
2. For transitive deps: the name field if specified, otherwise derived from path

## Dependencies

This agent uses the following helper:
- {{ agpm.deps.snippets.helper.install_path }}

{% if agpm.deps.agents %}
## Related Agents
{% for agent in agpm.deps.agents %}
- {{ agent.name }} ({{ agent.version }})
{% endfor %}
{% endif %}

Custom Names for Transitive Dependencies

---
dependencies:
  agents:
    - path: "../shared/complex-path/helper.md"
      name: "helper"  # Use "helper" instead of deriving from path
---

Conditional Content

{% if agpm.resource.source == "community" %}
This resource is from the community repository.
{% elif agpm.resource.source %}
This resource is from the {{ agpm.resource.source }} source.
{% else %}
This is a local resource.
{% endif %}

Modules

filters

Custom Tera filters for AGPM templates.

Structs

ResourceTemplateData

Metadata about a resource for template context.

TemplateContextBuilder

Template context builder for AGPM resource installation.

TemplateRenderer

Template renderer with Tera engine and custom functions.

Functions

to_native_path_display

Convert Unix-style path (from lockfile) to platform-native format for display in templates.