Managed Embedding

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:

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

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

<!-- 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:

<!-- 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:

.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:

.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. For the full generate/import sequence, see Generation Pipeline.