Let an agent edit the docs without letting it invent the system

The dangerous agent edit is rarely the sentence with bad grammar.

It is the polished pull request that places a file in the wrong collection, links to a route the site never generates, edits build/ because the HTML was easy to find, publishes a future announcement immediately, or copies a layout instead of using the project’s extension boundary.

The prose may sound confident. The repository model is still wrong.

TidyPress treats AI-assisted authorship as a coordination problem, not a text generation feature. An agent needs enough local guidance to understand the project, but guidance cannot be the final authority. The change must pass through the same executable boundaries as a human change.

The agent proposes. The repository records. The build refuses invalid work.

Markdown fluency is not repository fluency

A general coding agent already knows how to create headings, links, and frontmatter. What it cannot know in advance is the local meaning of those files.

In one TidyPress repository:

• writing may be a dated public journal;
• works may delegate to project behavior;
• process may be a navigable decision record;
• docs entries may use doc or manual forms;
• site/ may contain owned presentation extensions;
• build/ is generated and must never be edited;
• a scheduled entry may be valid source but intentionally absent from output.

Those rules are not Markdown syntax. They are the publication’s protocol.

If the agent does not learn them, it will substitute conventions from another framework or invent the missing structure. The result can be internally tidy and externally false.

Orientation should be explicit and inspectable

TidyPress ships Agent Skills that describe the project shape, common commands, collection behavior, configuration boundaries, and verification workflow. They are installed only through an explicit command:

npx tidypress skills install

The installer detects supported environments from existing agent directories or executables on PATH. Cursor and Codex can use the neutral .agents/skills location; Claude Code uses its own skills directory. Existing files are preserved unless the user intentionally passes --force.

This operation is deliberately separate from package installation. It does not edit shell profiles, add environment variables, rewrite agent settings, or run silently as a post-install script.

That restraint is part of the trust model. Installing a publishing dependency should not invisibly change how every agent on a machine behaves.

The skill is a map, not a law

Written guidance can drift. A model can misread it. A project can override the default shape. No prompt—however carefully written—should be the only thing standing between an agent and an invalid publication.

TidyPress therefore keeps authority executable:

• content schemas validate required frontmatter;
• configuration normalization rejects impossible combinations;
• the route planner catches collisions and missing structure;
• Astro rendering catches broken MDX and component use;
• search assets and llms.txt are produced from the public result;
• Git shows exactly what the agent changed.

The skill explains how to reach those boundaries. It does not replace them.

A safe edit has four phases

1. Orient

The agent reads AGENTS.md, the relevant skill, the site configuration, and the nearest existing content before proposing structure. It identifies the publish root and distinguishes source from generated output.

This phase prevents the most expensive category of mistake: solving the wrong repository problem cleanly.

2. Edit the owned source

The agent changes Markdown, MDX, configuration, assets, or an explicitly owned presentation extension. It does not patch generated HTML or framework cache files. It preserves unrelated work already present in the tree.

3. Prove the public result

A proportional check may be enough for a small copy edit. A new route or MDX component deserves a complete build. The important point is that the claim “this page works” comes from executable output, not from the agent’s reading of its own patch.

4. Return evidence to a reviewer

The diff should be small enough to understand. The rendered route should be available for inspection. If the change alters a public contract, the agent should explain that consequence rather than hiding it in implementation detail.

This loop is useful even when the author and reviewer are the same person. It separates generation from judgment.

Why not let the agent publish directly?

There are workflows where automatic merging is appropriate: fixing a verified broken link, updating a generated version table, or applying a deterministic format change. But prose often carries product intent, safety implications, and reputational judgment that a passing build cannot validate.

An article can compile and still misrepresent a result. A migration guide can link correctly and still omit the destructive step. A generated API reference can be structurally valid while exposing an internal symbol that should not be public.

The build proves mechanical coherence. A human still decides whether the work deserves to ship.

That is not an argument against automation. It is an argument for locating the remaining judgment honestly.

Future editors should write the same files

A visual editor can make this workflow accessible to somebody who does not want to operate Git from a terminal. It can offer previews, structured frontmatter, and calm writing tools. It should still round-trip to the same repository contract rather than creating a private document model behind the interface.

The same is true of a hosted build layer. It may connect a repository to a URL, provide logs, and make deployments easier. It should consume the source and produce the artifact without becoming the only database that understands the publication.

human editor ─┐
visual editor ├─> Markdown + config in Git ─> build ─> public artifact
coding agent ─┘

Different interfaces can participate because none of them owns the truth alone.

Git is not magically collaborative

This model has real costs. Merge conflicts exist. Nontechnical writers should not need to learn staging terminology. Large editorial organizations may need roles, comments, approvals, and workflows beyond what a repository provides by itself.

The answer is to build better interfaces over the repository, not to deny the cost or quietly replace the underlying source. TidyPress’s first audience—open- source maintainers, technical teams, researchers, and independent builders— already uses Git as the place where code, review, automation, and deployment meet. The publication can benefit from that existing accountability.

The goal is not an autonomous writer

The most useful agent is not the one that can produce the most pages. It is the one that can make a correct, bounded change in a system it understands and leave behind evidence a person can judge.

That requires more than a clever prompt. It requires visible source, local orientation, executable constraints, reviewable history, and an artifact that shows what actually shipped.

TidyPress does not ask the agent to become the publishing system. It gives the agent a disciplined way to participate in one.