Publish an agent integration guide and workflow examples

[adrianbrowning]

What to build

Publish a copyable agent integration guide that teaches coding agents how to use mdcode safely and predictably in a repository workflow.

Acceptance criteria

• The guide describes the inspect, plan, apply, and verify workflow using the public CLI contract.
• It includes concise examples for extraction, region synchronization, freshness checks, and targeted block selection.
• It states when commands are safe for untrusted Markdown and when explicit approval is required.
• Installation and import examples use the canonical package identity.
• The guide is usable as an agent skill or project instruction without repository-specific assumptions.

Blocked by

• Define the canonical npm package identity and align metadata #3
• Add a versioned machine-readable CLI contract for agents #5
• Add plan, diff, apply, and check workflows for agent-driven sync #6
• Harden mdcode operations for untrusted Markdown and agent execution #7

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Publish a portable, copyable guide for coding agents that use mdcode safely in repository workflows.

Current behavior:
The repository has internal agent-process documentation only. It has no user-facing guide that explains the mdcode workflow, safety boundaries, installation, or machine-readable results to a coding agent working in an arbitrary consumer repository.

Desired behavior:
A standalone guide can be copied into an agent skill or repository instruction. It teaches agents to inspect first, produce a plan, review a diff, apply explicitly, and verify synchronization. Examples use the canonical @gcmdev/mdcode identity and only describe finalized public behavior.

Key interfaces:

• Agent workflow — inspect named blocks, obtain a non-mutating plan, review a diff, apply explicitly, and use check for freshness verification.
• Extraction and region synchronization examples — demonstrate accurate public CLI invocations without repository-specific paths or tools.
• Targeted selection — use stable block names from issue Add stable block identities and robust metadata syntax #16.
• Safety model — distinguish safe inspection and planning from writes and shell execution; state when explicit approval, --apply, or --allow-shell is required.
• Machine-readable results — show how an agent consumes the versioned JSON contract without parsing human output.

Acceptance criteria:

• The guide describes inspect, plan, diff, apply, and verify steps using the public CLI contract.
• It includes concise, correct examples for extraction, region synchronization, freshness checks, and --name selection.
• It documents the trusted-input model, allowed-base behavior, and when human approval or explicit flags are required.
• Installation and import examples consistently use @gcmdev/mdcode.
• The guide is self-contained enough to serve as a reusable agent skill or project instruction.
• Every example is checked against the current public CLI and JSON contract.

Out of scope:

• A VS Code extension, editor diagnostics, or a runtime agent framework integration.
• Repository-specific CI configuration.
• Redefining the package identity, JSON response contract, sync workflow, or security rules.

Verification status:
Confirmed: no user-facing agent integration guide exists. This issue remains blocked by #3, #5, #6, and #7.