Use Merulan in a coding agent

Use this guide when you want a coding agent to change an integration that uses Merulan. You will give the agent the exact public contract, constrain the task, review its patch, and verify one result. The example reads a List. This workflow works with any coding agent. It does not give the agent direct access to your Workspace.

Before you start

• Choose one small change with a result you can inspect.
• Find the Capability page that owns the behavior and the Surface reference that owns the syntax.
• Remove credentials, customer data, and private source from anything you paste into an agent.
• Name one focused check before the agent edits code.

MCP owns direct agent access to Merulan. You do not need MCP for this guide. You will hand the agent a public documentation page instead.

Share the contract

Open the page that owns the work. Use a Capability page for product behavior. Use a Surface reference for exact API, SDK, CLI, or infrastructure syntax. For the example below, open Get lists.

In AI tools, choose Copy as Markdown and paste the result into your coding agent. You can also open the page in one of the listed agent destinations. The Markdown includes the page title, contract, and links without the reader chrome.

Copy into AGENTS.md

Copying one page works for one task. An agent that returns to the same repository next week starts from nothing again. AGENTS.md is the first file most coding agents read. A few lines there tell every later session where Merulan documentation lives.

## Merulan documentation

- Documentation root: https://merulan.com/docs/
- Curated index, to decide where to start: https://merulan.com/llms.txt
- Every page, grouped by section: https://merulan.com/llms-index.txt
- Every page, reader address beside Markdown address: https://merulan.com/sitemap.md
- One section: https://merulan.com/docs/surfaces/llms.txt, and the same path under
  getting-started, capabilities, architecture-center, and integrations
- Any page as Markdown: add `.md` to its path, as in
  https://merulan.com/docs/capabilities/records-lists.md
- Exact call syntax: https://merulan.com/docs/surfaces/api/reference/ for HTTP, and the
  reference under each other Surface for that Surface
- Search: the `search_docs` tool, when Merulan MCP is connected

Treat the linked page as the contract. Name the page that permits a change before
making it, and stop when no page answers the question. When the page and anything
else disagree, the page wins: it is republished when the product changes, and a
copy in this repository or in an earlier session is not.

The fragment carries links and no contract. A status code, header name, permission, or release status copied into a repository goes stale where the page it came from does not. The agent has no way to tell which of the two it is reading. For the same reason the fragment names no credential, no private repository path, and no install command.

Write a bounded request

Tell the agent what to change, which page is authoritative, when it must stop, and how to prove the result. This template keeps those decisions visible:

Use the attached Merulan documentation as the source of truth.
Fix the smallest contract mismatch in the named file.
Before editing, state the owning page and the exact mismatch.
Stop if the public contract does not answer the question.
After approval, show the diff and run: <focused check>.

Do not ask the agent to “make the integration work” without a boundary. That prompt does not say which contract wins, what may change, or how a reviewer will know the task is done.

Review the session

The example fixes one HTTP request. The Get lists reference requires both a bearer token and x-merulan-workspace-id. The first patch omitted the Workspace header, so the agent corrected that single mismatch and reran its focused check.

@@ -1,1 +1,6 @@return fetch(`${origin}/api/v1/lists/${listId}`);return fetch(`${origin}/api/v1/lists/${listId}`, {  headers: {    Authorization: `Bearer ${token}`,    'x-merulan-workspace-id': workspaceId,  },});

## Send the declared access context

File: `list-client.ts` (ts)

### Before
```ts
return fetch(`${origin}/api/v1/lists/${listId}`);
```

### After
```ts
return fetch(`${origin}/api/v1/lists/${listId}`, {
  headers: {
    Authorization: `Bearer ${token}`,
    'x-merulan-workspace-id': workspaceId,
  },
});
```

Success: the final diff matches the linked public contract, stays inside the approved task, and has a passing focused check.

Verify the result

Do not use the agent's summary as proof. Review the changed lines against the linked Merulan page. Run the named check yourself or inspect its full output. For a Merulan write, also use the method's documented readback. Record one of three outcomes: completed, needs input, or stopped.

The example is complete only when the request sends both required headers and the focused test observes them. A broad test command with no relevant assertion is not enough.

When it fails

The agent invents a contract

Cause: the proposal names a field, route, package, or permission that is not on the linked page. Recovery: stop the edit, open the exact Surface reference, and ask the agent to cite the line that permits the change.

The diff exceeds the task

Cause: the patch includes cleanup, renaming, or a second feature. Recovery: reject the patch and restate the one file, contract mismatch, and check that are in scope.

The check has no observable result

Cause: the agent reports success without output tied to the requested change. Recovery: run a focused check that fails when the contract mismatch returns. If that check cannot run, end the session as needs input.

Next steps

• API explains HTTP authentication, Workspace scope, terminals, and readback.
• Get lists is the exact method contract used in the example.
• Data Pipelines shows how a Capability owns product behavior while a Surface owns call syntax.
• MCP owns direct tool access when the public gateway is available.