---
draft: false
title: Managed Embedding
description: The AgentsMesh marker contract for embedding generated or recoverable canonical content inside agent tool files without duplicates or broken round trips.
---

AgentsMesh uses one embedding rule for every target:

> Anything generated by AgentsMesh and embedded inside another agent tool file must be wrapped in an `agentsmesh:*` managed block.

Targets can write different native files, but they should not invent separate inline formats for generated metadata or projected canonical content. The marker format is the stable contract that lets `generate` and `import` round-trip safely.

## Why this exists

Some tools support separate files for every canonical item. Others only expose one root instruction file, so AgentsMesh has to fold additional rules or generated guidance into that file.

Managed blocks make that safe:

- `generate` replaces the previous block instead of appending duplicates
- `import` can restore embedded content to canonical `.agentsmesh/` files
- reference rewriting can leave canonical embedded payloads untouched
- users can see which sections are managed by AgentsMesh
- every target follows the same convention

## Marker format

Managed blocks use HTML comments:

```markdown
<!-- agentsmesh:<name>:start -->
generated content
<!-- agentsmesh:<name>:end -->
```

When the block must be imported back to canonical files, the start marker carries JSON metadata:

```markdown
<!-- agentsmesh:<name>:start {"source":"rules/typescript.md"} -->
canonical payload
<!-- agentsmesh:<name>:end -->
```

Metadata should use canonical paths relative to `.agentsmesh/`, such as `rules/typescript.md`. It should not use generated output paths such as `GEMINI.md`, `AGENTS.md`, or `.cursor/AGENTS.md`.

## Additional rules example

When a target folds additional rules into a root instruction file, AgentsMesh writes a managed collection:

```markdown
<!-- agentsmesh:embedded-rules:start -->
<!-- agentsmesh:embedded-rule:start {"source":"rules/typescript.md","description":"TypeScript-specific coding standards","globs":["src/**/*.ts","tests/**/*.ts"],"targets":[]} -->
## TypeScript-specific coding standards
# TypeScript Standards

- Use strict mode
- Prefer `unknown` over `any`
<!-- agentsmesh:embedded-rule:end -->
<!-- agentsmesh:embedded-rules:end -->
```

On import, AgentsMesh removes that block from the root file and restores the rule to:

```text
.agentsmesh/rules/typescript.md
```

The marker metadata restores the rule description, globs, and target scoping. The generated target filename is not used as the canonical source.

## Current block types

| Block | Used for | Round-trip behavior |
|-------|----------|---------------------|
| `agentsmesh:root-generation-contract` | The generated root instruction paragraph that tells agents to edit `.agentsmesh/` instead of generated files. | Stripped on import. |
| `agentsmesh:embedded-rules` | Outer container for additional rules embedded in an aggregate/root instruction file. | Removed from root content after extraction. |
| `agentsmesh:embedded-rule` | One additional rule inside `embedded-rules`. | Restored to `.agentsmesh/<source>`. |
| `agentsmesh:codex-rule-index` | Generated Codex index of additional instruction files. | Stripped on Codex import. |

## Matrix reporting

The support matrices separate root rule support from additional rule projection:

- **Rules** describes root-rule support and the target's general rule capability.
- **Additional Rules** describes how non-root `rules/*.md` files are projected.

When the **Additional Rules** row says **Embedded**, AgentsMesh writes those non-root rules into an aggregate/root instruction file with managed metadata. When it says **Native**, the target gets separate rule files in its own rule format. **Partial** means the target has an aggregate global surface that does not have the full managed-block round-trip contract.

## Generate flow

1. Load canonical content from `.agentsmesh/`, installed packs, and extends.
2. Generate target-native artifacts.
3. If a canonical item must be folded into a larger target file, render it as a managed block.
4. Add generated-only managed sections, such as the root generation contract.
5. Rewrite references, while protected managed payloads stay canonical.
6. Write files and update the lock file.

Because generation replaces existing managed blocks, running `agentsmesh generate` repeatedly does not re-append the same embedded content.

## Import flow

1. Read the target-native file.
2. Strip generated-only managed blocks.
3. Extract recoverable blocks into canonical `.agentsmesh/` files.
4. Normalize references in the remaining target-authored content.
5. Write canonical files.

This keeps `.agentsmesh/` as the source of truth even when a target needs aggregate files.

## Authoring guidance

Edit canonical files, not managed generated blocks:

```text
.agentsmesh/rules/_root.md
.agentsmesh/rules/*.md
.agentsmesh/commands/*.md
.agentsmesh/agents/*.md
.agentsmesh/skills/*/SKILL.md
```

Generated tool files are safe to inspect, but managed blocks may be replaced on the next `agentsmesh generate`.

For rule authoring details, see [Rules](../../canonical-config/rules/). For the full generate/import sequence, see [Generation Pipeline](./generation-pipeline/).
